What Is an AI Earnings Analysis Agent?

An earnings analysis agent is a software system that automatically acquires, parses, validates, and analyzes company results. It combines deterministic data processing with an LLM. The data layer retrieves reported results and supporting evidence; Python calculates changes and surprise values; the model explains the evidence in a consistent report.

A useful agent can extract EPS, revenue, gross margin, operating income, free cash flow, segment performance, and management guidance. It can compare those values with prior quarters, year-over-year periods, and analyst expectations. It can flag anomalies such as revenue growth with deteriorating cash conversion, a guidance cut despite an EPS beat, or a margin change that does not match management commentary.

The final output should be structured rather than a free-form paragraph. A production report may include reported values, consensus, surprise percentages, historical deltas, management guidance, notable transcript statements, risks, citations, and confidence. JSON output lets another service store the report, rank surprises, trigger alerts, or render a user interface.

Developers build an earnings analysis AI agent when they need control over the universe, schedule, evidence, calculations, prompts, and destination. Existing research products are often faster for interactive human analysis. A custom agent is justified when the process must cover hundreds of tickers, run automatically, integrate with proprietary models, or produce an application-specific schema.

Key Capabilities for an AI Earnings Analysis Agent

The quality of the report cannot exceed the quality and compatibility of its inputs. Five capability groups form the minimum useful foundation.

Also define freshness and failure rules. If consensus is unavailable, the agent should say so rather than treating zero as the estimate. If two providers disagree, retain both values, identify their sources, and route the discrepancy for human review.

Why QVeris Supports Automated Earnings Analysis

QVeris provides a unified Discover → Inspect → Call protocol across more than 10,000 capabilities. Instead of maintaining independent adapters for Alpha Vantage, Finnhub, Polygon.io, filing systems, news feeds, and other providers, a developer can search by intent and inspect candidate schemas before execution.

Discover finds relevant capabilities using natural language. Inspect returns parameters, examples, available statistics, and billing information without consuming execution credits. Call runs the selected capability and returns a typed response with structured results and execution metadata. The official asynchronous Python SDK also exposes usage and ledger methods for auditing calls and charges.

QVeris supports MCP for Claude Code, Cursor, OpenCode, and compatible clients, plus Python SDK, REST API, and CLI integrations. Discover and Inspect are currently free. Signup includes 1,000 credits and daily login provides 100 credits under the current program; verify production costs on the pricing page.

This does not eliminate provider-specific considerations. Developers must still validate licensing, exchange entitlements, freshness, field definitions, and coverage. QVeris is the routing and execution foundation; application code remains responsible for normalization, calculations, review policy, and investment-use controls.

Step-by-Step: Build an Earnings Analysis Agent

Install the official packages with pip install qveris anthropic. QVeris SDK methods are asynchronous, so the examples use asyncio. Store both API keys in environment variables.

import asyncio
import json
import os
from datetime import datetime, timezone

from qveris import QverisClient

TICKER = "AAPL"
REQUIRED_METRICS = ["eps", "revenue", "gross_margin", "guidance"]

async def create_client():
    # QverisClient reads QVERIS_API_KEY from the environment.
    return QverisClient()

async def discover_earnings_tools(client):
    query = (
        "earnings per share, revenue, gross margin, "
        "analyst estimates, and company guidance for US stocks"
    )
    discovered = await client.discover(query, limit=10)

    if not discovered.results:
        raise RuntimeError("No earnings capabilities found")

    for tool in discovered.results:
        print(tool.tool_id, tool.name)
    return discovered

async def inspect_earnings_tool(client, discovered):
    candidate_ids = [tool.tool_id for tool in discovered.results[:3]]
    inspected = await client.inspect(
        candidate_ids,
        search_id=discovered.search_id,
    )

    for tool in inspected.results:
        print("TOOL:", tool.tool_id)
        print("PARAMS:", [p.model_dump() for p in tool.params])
        print("BILLING:", tool.billing_rule)

    # Replace this simple selection with your own policy.
    return inspected.results[0]

async def fetch_latest_earnings(client, tool, search_id):
    params = {}
    if tool.examples and tool.examples.sample_parameters:
        params.update(tool.examples.sample_parameters)

    # Confirm these names against tool.params after Inspect.
    params.update({"ticker": TICKER, "limit": 4})

    response = await client.call(
        tool.tool_id,
        params,
        search_id=search_id,
        max_response_size=50_000,
    )
    if not response.success:
        raise RuntimeError(response.error_message)

    return {
        "execution_id": response.execution_id,
        "data": response.result,
        "cost": response.cost,
        "remaining_credits": response.remaining_credits,
    }

from anthropic import Anthropic

def analyze_with_claude(packet):
    claude = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
    prompt = f"""
Analyze the earnings evidence below for {TICKER}.
Use only supplied data. Do not invent estimates or guidance.
Return valid JSON with:
summary, reported_metrics, surprises, historical_changes,
guidance, anomalies, risks, missing_data, and citations.

Evidence:
{json.dumps(packet["data"], default=str)}
"""
    message = claude.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=2500,
        temperature=0,
        messages=[{"role": "user", "content": prompt}],
    )
    return message.content[0].text

async def run_once():
    client = await create_client()
    try:
        discovered = await discover_earnings_tools(client)
        tool = await inspect_earnings_tool(client, discovered)
        packet = await fetch_latest_earnings(
            client, tool, discovered.search_id
        )
        report = analyze_with_claude(packet)
        print(datetime.now(timezone.utc).isoformat(), report)
    finally:
        await client.close()

async def scheduler():
    while True:
        await run_once()
        # Run every six hours; replace with event-driven scheduling.
        await asyncio.sleep(6 * 60 * 60)

if __name__ == "__main__":
    asyncio.run(scheduler())

Keep a last-processed filing or event identifier so repeated runs do not publish duplicate reports. Store raw evidence, execution IDs, normalized metrics, prompt versions, and generated output. Audit credit outcomes through QVeris usage or ledger methods, and never treat a successful capability call as proof that the financial interpretation is correct.

Normalize and Validate Before the LLM

Convert currencies and units, align fiscal periods, distinguish GAAP from non-GAAP EPS, and calculate surprises with explicit formulas. Reject impossible values and label missing fields. This validation layer is what turns a demo into a dependable automated earnings analysis pipeline.

Production Architecture for Automated Earnings Analysis

Use Events When Available, Polling When Necessary

The best trigger is a filing, earnings-release, or provider webhook with a unique event identifier and publication timestamp. Event-driven execution reduces unnecessary calls and shortens the delay between publication and analysis. Polling remains useful when a source has no webhook, but the scheduler should use an earnings calendar, market timezone, and last-processed state instead of querying every company continuously.

Make every run idempotent. Build a key from the ticker, fiscal period, event type, and source identifier. If an event arrives twice, update the existing record instead of creating a second alert. Keep separate states for data collected, normalized, analyzed, and reviewed so a failed LLM request can be retried without buying the same financial data again.

Preserve Point-in-Time Data

Consensus estimates and company guidance change over time. Store both the value and the timestamp at which the agent observed it. A backtest that compares reported EPS with today's revised consensus introduces look-ahead bias. The same rule applies to restatements: preserve the original observation and append revisions with explicit version metadata.

Maintain raw and normalized layers. Raw responses support audits and reprocessing after normalization code changes. The normalized layer gives factor pipelines and models stable fields. Never overwrite source evidence with an LLM summary.

Control Concurrency, Cost, and Failure Recovery

Earnings cluster after market close, so hundreds of companies may trigger at once. Use a queue and bounded workers rather than unlimited coroutines. Set per-capability timeouts, retry only transient errors, and apply exponential backoff with jitter. Send invalid parameters and unsupported tickers to a dead-letter queue for investigation.

Track discovery, execution, model, storage, and notification costs separately. Set a maximum cost per company and stop optional enrichment when the budget is exhausted. A concise report based on core evidence is better than an expensive report with redundant news and repeated calls.

Evaluate Facts, Not Stock Direction

Create a historical evaluation set containing releases, estimates available before publication, filings, and expected calculations. Test whether the agent extracted correct numbers, calculated surprise consistently, cited the correct source, identified missing data, and followed the output schema. Do not grade the system by whether the stock later rose or fell.

Add adversarial cases such as conflicting EPS definitions, currencies in thousands versus millions, fiscal-year changes, preliminary releases, restatements, and empty guidance. A production agent should fail clearly on ambiguous evidence instead of producing a confident unsupported conclusion.

Real-World AI Agent Financial Analysis Use Cases

Each use case needs different latency and licensing. A personal delayed-data workflow is not equivalent to an institutional real-time product. Confirm redistribution rights, provider terms, and exchange entitlements before exposing results to customers.

Advanced Features for an Earnings Analysis AI Agent

Additional production features include source-level confidence, fallback tools, transcript citation extraction, human feedback, prompt regression tests, and evaluation sets from historical earnings. Measure factual accuracy and citation validity rather than whether the stock later moved in the predicted direction.

Launch Checklist for an Earnings Analysis AI Agent

Before release, verify that every reported metric includes a period, currency, unit, source, and observation timestamp. Confirm that consensus data was available before the earnings event and that surprise calculations use one documented formula. Test duplicate events, missing estimates, restated results, provider timeouts, malformed JSON, and model responses that do not match the required schema.

Review data licenses for internal analysis, customer display, storage, and redistribution. Add role-based access to expensive or restricted capabilities, redact secrets from logs, and establish a maximum call and model budget per report. Finally, define who reviews high-impact alerts, how corrections are issued, and how long raw evidence is retained. These operational decisions are part of the product, not optional infrastructure work after the agent is launched.

Deploy an AI Earnings Analysis Agent Responsibly

To build an earnings analysis agent, define the research schema, discover and inspect appropriate capabilities, retrieve evidence, normalize calculations, generate a structured narrative, and schedule the process with audit logs. QVeris reduces multi-provider integration work, while Python and Claude handle application logic and explanation.

A reliable AI earnings analysis agent should accelerate review without hiding uncertainty. Preserve sources, validate numbers, disclose missing data, and keep humans responsible for investment decisions.

什么是 AI Earnings Analysis Agent

财报分析 Agent 是自动获取、解析、验证和分析公司业绩的软件系统。数据层获取报告值和证据，Python 计算变化与 surprise，LLM 根据证据生成一致报告。

它可以提取 EPS、营收、毛利率、营业利润、自由现金流、分部表现和管理层指引，并与历史季度、同比数据和分析师预期比较。它还能识别营收增长但现金转换恶化、EPS 超预期却下调指引等异常。

最终输出应采用 JSON，包括报告值、共识、超预期比例、历史变化、指引、风险、引用和置信度。开发者在需要覆盖数百只股票、自动运行、连接自有模型或输出定制 schema 时，才更适合自行构建。

AI Earnings Analysis Agent 的五项必备能力

如果共识缺失，Agent 必须明确标记，而不是把零当作预期。供应商数据冲突时，应保留双方结果并进入人工审核。

为什么 QVeris 适合 Automated Earnings Analysis

QVeris 通过统一 Discover → Inspect → Call 协议提供 10,000 多项能力，开发者无需分别维护 Alpha Vantage、Finnhub、Polygon、公告和新闻供应商适配器。

Discover 按意图寻找能力；Inspect 免费返回参数、示例、统计和计费信息；Call 执行并返回结构化结果与 execution metadata。官方异步 Python SDK 还提供 usage 和 ledger 方法。

QVeris 支持 MCP、Claude Code、Cursor、OpenCode、Python SDK、REST 和 CLI。注册当前赠送 1,000 积分，每日登录提供 100 积分；生产成本应查看价格页面。开发者仍需自行验证授权、数据时效、字段定义和覆盖。

Step-by-Step：构建 Earnings Analysis AI Agent

安装 pip install qveris anthropic，并设置 QVERIS_API_KEY 与 ANTHROPIC_API_KEY。

import asyncio, json, os
from datetime import datetime, timezone
from qveris import QverisClient

TICKER = "AAPL"

async def create_client():
    return QverisClient()

async def discover_tools(client):
    result = await client.discover(
        "earnings per share, revenue, margins, "
        "analyst estimates and guidance for US stocks",
        limit=10,
    )
    if not result.results:
        raise RuntimeError("没有找到财报能力")
    return result

async def inspect_tool(client, discovered):
    ids = [x.tool_id for x in discovered.results[:3]]
    inspected = await client.inspect(
        ids, search_id=discovered.search_id
    )
    for tool in inspected.results:
        print(tool.tool_id, tool.params, tool.billing_rule)
    return inspected.results[0]

async def fetch_earnings(client, tool, search_id):
    params = {"ticker": TICKER, "limit": 4}
    response = await client.call(
        tool.tool_id, params,
        search_id=search_id,
        max_response_size=50_000,
    )
    if not response.success:
        raise RuntimeError(response.error_message)
    return response.result

from anthropic import Anthropic

def analyze(data):
    claude = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
    prompt = f"""
仅使用以下证据分析 {TICKER} 财报。
返回 JSON：summary、reported_metrics、surprises、
historical_changes、guidance、anomalies、risks、
missing_data、citations。
证据：{json.dumps(data, default=str)}
"""
    msg = claude.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=2500,
        temperature=0,
        messages=[{"role": "user", "content": prompt}],
    )
    return msg.content[0].text

async def run_once():
    client = await create_client()
    try:
        discovered = await discover_tools(client)
        tool = await inspect_tool(client, discovered)
        data = await fetch_earnings(
            client, tool, discovered.search_id
        )
        print(analyze(data))
    finally:
        await client.close()

async def scheduler():
    while True:
        await run_once()
        await asyncio.sleep(6 * 60 * 60)

asyncio.run(scheduler())

保存最后处理的事件 ID，避免重复报告；记录原始证据、execution ID、归一化指标、提示词版本和输出，并通过 usage 或 ledger 审计积分。

LLM 前的数据验证

统一币种、单位和财年，区分 GAAP 与 non-GAAP EPS，用明确公式计算 surprise，拒绝不可能数值并标记缺失字段。

AI Agent Financial Analysis 的真实场景

不同场景的数据时效和授权不同。向客户展示结果前必须确认再分发权、供应商条款和交易所授权。

Earnings Analysis AI Agent 的高级功能

生产系统还可以增加来源置信度、备用能力、电话会引用、人工反馈和历史财报评估集。

负责任地部署 AI Earnings Analysis Agent

要 build earnings analysis agent，需要定义研究 schema、发现并检查能力、获取证据、统一计算、生成结构化报告并加入定时和审计。QVeris 降低多供应商集成成本，Python 与 Claude 负责业务逻辑和解释。

可靠的 AI earnings analysis agent 应提高审核效率而不是隐藏不确定性。保留来源、验证数字、披露缺失数据，并让人类负责投资决策。