feat(examples): add FXMacroData macro research example

examples/README.md

@@ -105,6 +105,7 @@ Create a multi-agent research workflow where different AI agents collaborate to
 - [Custom Endpoints](./with-custom-endpoints) — Add bespoke REST endpoints alongside agent/workflow routes.
 - [Dynamic Parameters](./with-dynamic-parameters) — Validate and inject runtime parameters into agents with Zod.
 - [Dynamic Prompts](./with-dynamic-prompts) — Build prompts from templates and live data programmatically.
+- [FXMacroData](./with-fxmacrodata) — Answer macro questions with official CPI, GDP, policy-rate and release-calendar data from FXMacroData tools.
 - [Google AI](./with-google-ai) — Use Google Gemini models via the AI SDK provider.
 - [Google Drive (MCP)](./with-google-drive-mcp) — Browse and read Drive files through a Google Drive MCP server.
 - [Google Vertex AI](./with-google-vertex-ai) — Connect agents to Vertex AI models in your GCP project.

examples/with-fxmacrodata/.env.example

@@ -0,0 +1,3 @@
+OPENAI_API_KEY=your_openai_api_key_here
+# Optional: USD data works without a key
+FXMACRODATA_API_KEY=

examples/with-fxmacrodata/README.md

@@ -0,0 +1,85 @@
+# VoltAgent with FXMacroData
+
+This example gives a VoltAgent research agent tools for official macroeconomic data from [FXMacroData](https://fxmacrodata.com/documentation/reference?utm_source=github&utm_medium=referral&utm_campaign=voltagent&utm_content=readme): indicator releases with their publication times, release calendars and FX rates.
+
+## Features
+
+- List the indicators available for a currency (CPI, GDP, policy rate, payrolls, bond yields and more)
+- Fetch released values with the period, the publication timestamp and the official source link
+- Fetch the upcoming release calendar, with times in UTC and the publisher's local time
+- Fetch daily FX rates for a currency pair
+
+## Prerequisites
+
+1. **OpenAI API Key**: Used by the example agent model
+2. **FXMacroData API Key** (optional): USD releases from the last 90 days, the USD calendar and the indicator catalogue work without a key. Older history, other currencies and FX rates need one, see [plans](https://fxmacrodata.com/subscribe?utm_source=github&utm_medium=referral&utm_campaign=voltagent&utm_content=readme)
+
+## Setup
+
+1. Install dependencies:
+
+   ```bash
+   pnpm install
+   ```
+
+2. Configure environment variables:
+
+   ```bash
+   cp .env.example .env
+   ```
+
+   Then edit `.env`:
+
+   ```env
+   OPENAI_API_KEY=your_openai_api_key_here
+   FXMACRODATA_API_KEY=
+   ```
+
+3. Run the example:
+
+   ```bash
+   pnpm dev
+   ```
+
+The agent runs on the default VoltAgent server port and exposes one agent named `macroResearchAgent`.
+
+## Tools Available
+
+### 1. List Indicators
+
+- **Purpose**: List indicator slugs, names, units and sources for a currency
+- **Endpoint**: `GET /v1/data_catalogue/{currency}`
+
+### 2. Get Indicator History
+
+- **Purpose**: Released values for one indicator, newest first
+- **Endpoint**: `GET /v1/announcements/{currency}/{indicator}`
+- **Parameters**:
+  - `currency`: Three-letter code such as `usd`
+  - `indicator`: Slug such as `inflation` or `policy_rate`
+  - `startDate`, `endDate`: Optional `YYYY-MM-DD` bounds
+  - `limit`: Maximum rows (default 12)
+
+### 3. Get Release Calendar
+
+- **Purpose**: Scheduled releases for a currency
+- **Endpoint**: `GET /v1/calendar/{currency}`
+- **Parameters**:
+  - `indicator`: Optional slug filter
+  - `startDate`, `endDate`: Optional `YYYY-MM-DD` bounds
+
+### 4. Get FX Rates
+
+- **Purpose**: Daily rates for a currency pair (needs an API key)
+- **Endpoint**: `GET /v1/forex/{base}/{quote}`
+
+## Example Prompts
+
+- "What was the latest US CPI print and when was it published?"
+- "When are the next US payrolls and CPI releases?"
+- "How has the Fed's policy rate moved this year?"
+- "Compare the latest euro area and UK inflation" (needs an API key)
+
+## Notes
+
+The tools return the API response unchanged, so the agent sees units, source links and data-quality fields as published. Redirects are refused, so the key header is only ever sent to `api.fxmacrodata.com`, and the key is removed from error text. Responses are not cached; the keyless tier has a fair-use allowance of 100 requests per day.

examples/with-fxmacrodata/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "voltagent-example-with-fxmacrodata",
+  "author": "",
+  "dependencies": {
+    "@voltagent/cli": "^0.1.21",
+    "@voltagent/core": "^2.11.0",
+    "@voltagent/logger": "^2.0.2",
+    "@voltagent/server-hono": "^2.0.14",
+    "ai": "^6.0.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^24.2.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.2"
+  },
+  "keywords": [
+    "agent",
+    "ai",
+    "economic-calendar",
+    "fxmacrodata",
+    "macroeconomics",
+    "voltagent"
+  ],
+  "license": "MIT",
+  "private": true,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/VoltAgent/voltagent.git",
+    "directory": "examples/with-fxmacrodata"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch --env-file=.env ./src",
+    "start": "node dist/index.js",
+    "volt": "volt"
+  },
+  "type": "module"
+}

examples/with-fxmacrodata/src/index.ts

@@ -0,0 +1,30 @@
+import { Agent, VoltAgent } from "@voltagent/core";
+import { createPinoLogger } from "@voltagent/logger";
+import { honoServer } from "@voltagent/server-hono";
+import { fxmacrodataTools } from "./tools.js";
+
+const logger = createPinoLogger({
+  name: "fxmacrodata-agent",
+  level: "info",
+});
+
+const macroResearchAgent = new Agent({
+  name: "macro-research-agent",
+  instructions: `You answer macroeconomic and FX questions with FXMacroData tools.
+
+Use listIndicators when you need an indicator slug, getIndicatorHistory for released values,
+getReleaseCalendar for what is scheduled next, and getFxRates for exchange rates.
+Quote each value with the period it refers to and when it was published, and cite the source link.
+If a tool returns HTTP 401 or 403, say that the currency or dataset needs an FXMacroData API key
+rather than guessing a number.`,
+  model: "openai/gpt-4o-mini",
+  tools: fxmacrodataTools,
+});
+
+new VoltAgent({
+  agents: {
+    macroResearchAgent,
+  },
+  logger,
+  server: honoServer(),
+});