FXMacroData for Pydantic AI

Bring your FXMacroData subscription into Pydantic AI agents for cross-currency macro research, available indicator histories, FX reference rates, commodities and release analysis. Each operation is a native tool with its own input schema; results retain the data, units and source provenance.

Subscribe to FXMacroData to access the datasets and history available to your plan. Public USD catalogue, recent indicator history and calendar access let you evaluate the integration before subscribing, without an API key or account.

Install

Requires Python 3.10+ and Pydantic AI 2.42.0 or later in the 2.x series. This version is supplied as source and wheels; it has not been published to PyPI. Install both supplied wheels from their download directory:

python -m pip install ./fxmacrodata_public_client-0.1.1-py3-none-any.whl ./pydantic_ai_fxmacrodata-0.1.0-py3-none-any.whl

Alternatively, after installing the supplied public-client wheel, install this source directory with python -m pip install .. Install the Pydantic AI provider extra for your chosen model as described in the Pydantic AI installation guide.

Connect your subscription

Configure FXMACRODATA_API_KEY in your application's secret store or environment; FXMD_API_KEY is also supported. Set PYDANTIC_AI_MODEL to the model identifier used by your application and configure that provider's credentials normally.

import asyncio
import os

from pydantic_ai import Agent
from pydantic_ai_fxmacrodata import FXMacroDataToolset

agent = Agent(
    os.environ["PYDANTIC_AI_MODEL"],
    toolsets=[FXMacroDataToolset()],
)


async def main():
    result = await agent.run(
        "Compare the latest available US and euro-area policy rates. "
        "Cite the source and report missing publication times as unknown."
    )
    print(result.output)


asyncio.run(main())

No key is passed in a prompt or tool call. Settings also accept Pydantic SecretStr values. Their representation and serialized configuration omit the API key. Model-provider usage is billed separately by your provider.

Tool discovery and selection

The default toolset registers 79 tools: 29 REST operations and 50 hosted MCP tools. The operation matrix lists the exact inventory. This includes the research panel, announcement changes, bounded event captures, prediction coverage, visual artifacts and hosted research tasks.

Tool names have an fxmd_ prefix. For example, indicator_history becomes fxmd_indicator_history, and mcp_known_at_time_task becomes fxmd_mcp_known_at_time_task. Every tool retains its original public input schema; required fields, nested request bodies, optional fields and defaults remain intact. A schema default is documented, not silently inserted into a call.

Select a smaller set when an agent has a focused job:

from pydantic_ai_fxmacrodata import FXMacroDataToolset

macro_tools = FXMacroDataToolset(
    operations=["data_catalogue", "indicator_history", "release_calendar"],
    id="macro_research",
)
print(macro_tools.available_operations())

Use include_mcp=False to register only REST tools. Native Pydantic AI filtered, prefixed and renamed toolset wrappers also work. With multiple FXMacroData toolsets on one agent, give each a distinct id and tool prefix.

Data and provenance

Each successful tool returns an FXMacroDataResult Pydantic model:

Field	Meaning
operation	Original public operation name
data	Original response, including metadata and pagination
records	Additive record view of the same response
source_url	Credential-free endpoint or FXMacroData attribution URL

data and records describe the same observations. Source URLs, units, publication-time status, unavailable values and revision metadata remain as provided. Pagination remains visible: an individual tool invocation retrieves the requested page, and the agent can request further pages using the operation's cursor fields. The adapter does not describe a single page as complete history. The event-stream tool captures a bounded batch, rather than keeping the model call open indefinitely. Hosted visual-artifact URLs remain in their original response; this package does not render or download them.

For the endpoint contract and access details, see the FXMacroData API reference.

Execution and errors

Each agent run receives an independent executor, with four concurrent calls by default. Each call creates and closes its own HTTP session, including hosted MCP initialization and teardown. Configure limits through FXMacroDataSettings:

from pydantic_ai_fxmacrodata import FXMacroDataSettings, FXMacroDataToolset

tools = FXMacroDataToolset(
    FXMacroDataSettings(
        request_timeout_seconds=30,
        tool_timeout_seconds=90,
        max_concurrency=4,
    )
)

Invalid arguments produce Pydantic AI ModelRetry feedback without quoting the rejected input. Access, rate-limit and transport failures produce ToolFailed feedback without response bodies or authenticated URLs.

Cancellation returns control to the agent immediately and cancels queued calls. A synchronous HTTP call already in progress cannot be interrupted by Python task cancellation; it finishes within the public client's request bounds, then closes its session. A tool deadline likewise stops waiting for that result. The executor keeps its concurrency limit while an in-flight call drains.

This package targets ordinary Pydantic AI Agent runs. Durable workflow engines need their own activity/replay integration; attaching this custom executing toolset to a durable agent does not provide replay safety.

Tests and builds

python -m pip install ".[test]" build
python -m pytest tests -q
python -m build

Tests exercise every registered operation through an actual Pydantic AI agent and the public client's mocked REST/MCP transport. They make no model-provider requests and need no FXMacroData credentials.