FXMacroData for the OpenAI Agents SDK

Give an OpenAI Agents SDK agent every public FXMacroData operation as a function tool: macroeconomic releases, central-bank decisions, release calendars, FX reference rates, commodities, positioning and research tools. Each of the 87 REST operations and MCP tools becomes one FunctionTool whose name, description and parameter schema come straight from the public operation catalogue, so the model sees the same contract the documentation describes.

Explore FXMacroData

Install

Install the openai-agents-fxmacrodata wheel together with its fxmacrodata-platform-core and fxmacrodata-public-client dependencies. From the supplied packages directory:

python -m pip install ./fxmacrodata-public-client ./fxmacrodata-platform-core ./openai-agents-fxmacrodata

Use with an agent

from agents import Agent, Runner
from openai_agents_fxmacrodata import tools

agent = Agent(
    name="Macro analyst",
    instructions="Answer with the official release values and cite the source_url.",
    tools=tools(
        api_key_env="FXMD_API_KEY",
        include=["indicator_history", "release_calendar", "latest_announcements"],
    ),
)
result = Runner.run_sync(agent, "What is the latest US policy rate decision?")
print(result.final_output)

Omit include to expose every operation, or pass exclude to drop a few. MCP tools keep their mcp_ prefix. Unknown names raise ValueError before any request is made. The tools are built with strict_json_schema=False because several operations have optional parameters; the parameter schema itself forbids unknown keys and every call is validated before it is sent.

Credentials

Set FXMD_API_KEY (or any name you prefer) in your environment or secret manager and pass its name through api_key_env. The value is read only while a tool executes; it is never stored on the tools, never placed in a tool description or schema, and never shown to the model. A tool call that tries to pass an API key, token or URL as an argument is rejected with a short error message. Omitting api_key_env selects anonymous access, which serves the USD catalogue and is enough to evaluate the tools.

Bounded tool output

Every tool returns a compact JSON string with operation, source_url, record_count, the first max_records records (default 200) and a truncated flag. The complete response envelope is included as response while the whole document fits in max_chars (default 60,000 characters); otherwise it is omitted and records are trimmed until the document fits, so a long history can never flood a model context. Failed reads return {"error": "..."} rather than raising, so the agent can adjust its arguments and retry. Reads run in a worker thread and never block the event loop.

For the complete, unbounded response in your own code, use the plain helper:

from openai_agents_fxmacrodata import fetch

batch = fetch("indicator_history", {"currency": "usd", "indicator": "policy_rate"})
batch.payload      # original response envelope
batch.records()    # list of records
batch.rows()       # tabular rows with record_json and response_json

Historical operations follow every page by default (complete_history=True, max_pages=1000). Calendar and observation times keep the API's original strings; nothing is inferred.

Full operation reference: https://fxmacrodata.com/documentation/reference?utm_source=github&utm_medium=referral&utm_campaign=openai-agents-fxmacrodata&utm_content=readme

Development

Run the offline tests with python -m pytest tests. They build the tools, invoke them against fixture responses and never call the live service.