Agent Integration

Connect FinData4AI to AI agents by mapping financial research jobs to safe, sourced tools.

FinData4AI is designed around financial research jobs: retrieve the smallest useful dataset, preserve source metadata, and pass compact context to the model. Treat the API contract as the source for tool schemas, and treat market coverage as part of planning.

Integration surfaces

Surface	Use it for
REST API	Production server-side calls from your app or agent backend.
OpenAPI schema	Generate typed tools, validate parameters, and keep request examples in sync.
`llms.txt`	Let agent runtimes discover docs, coverage notes, and important entry points.
Coverage roadmap	Keep preview and roadmap tools out of autonomous plans until you provide a fallback.

Tool planning pattern

Build tools around user jobs, not around every possible endpoint.

const plan = [
  {
    tool: 'get_income_statements',
    args: { market: 'hk', ticker: '00700', period: 'annual' },
    purpose: 'Normalize revenue and operating margins.',
  },
  {
    tool: 'get_sec_filings',
    args: { market: 'us', ticker: 'NVDA', form_type: '10-K' },
    purpose: 'Extract risk factors and management discussion.',
  },
  {
    tool: 'get_prices',
    args: { market: 'cn', ticker: '600519', interval: '1d' },
    purpose: 'Check whether price action needs event context.',
  },
];

Example tool schema

Expose read-only tools with explicit market and ticker parameters. Keep authentication server-side.

{
  "name": "get_income_statements",
  "description": "Return normalized income statements for one listed company.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "market": {
        "type": "string",
        "enum": ["us", "hk", "cn"],
        "description": "Equity market."
      },
      "ticker": {
        "type": "string",
        "description": "Ticker in the selected market, such as AAPL, 00700, or 600519."
      },
      "period": {
        "type": "string",
        "enum": ["annual", "quarterly"],
        "default": "annual"
      }
    },
    "required": ["market", "ticker"]
  }
}

MCP gateway shape

If your environment uses an MCP gateway, expose a small set of validated tools first. Add preview and roadmap tools only after your application has coverage checks and fallbacks.

{
  "server": "findata4ai",
  "tools": [
    "get_prices",
    "get_company_facts",
    "get_income_statements",
    "get_balance_sheets",
    "get_cash_flow_statements",
    "get_sec_filings",
    "get_news"
  ],
  "env": {
    "FINDATA4AI_API_KEY": "fd4a_..."
  }
}

What to pass into the model

Pass compact, cited context. Do not pass full raw filings unless the task truly requires it.

{
  "question": "What changed in margin risk?",
  "market": "hk",
  "ticker": "00700",
  "fields": {
    "revenue": "...",
    "operating_margin": "..."
  },
  "sources": [
    {
      "type": "financial_statement",
      "title": "Annual results",
      "published_at": "2026-03-28",
      "url": "https://..."
    }
  ],
  "market_notes": [
    "HK reporting labels may differ from US GAAP labels."
  ]
}

Coverage stages

Stage	Agent behavior
Available now	The agent may plan and call the tool after user authorization and server-side auth.
Preview / limited	The agent may use the tool only with fallback logic and user-visible coverage notes.
Roadmap	Mention as requested coverage, but do not let the model call it.

Guardrails

Keep API keys server-side.
Filter tools by market before planning.
Include source links, report dates, and market notes in final answers.
Log request IDs, status codes, latency, and credits.
Do not let the model infer unsupported market coverage.