How to build a Financial Research Agent with SEC Filings and Market Data

Day 5 of 30 Days of Search.

Quick Summary: You read the company’s filings, check the share price, and work through the numbers in a spreadsheet. Then you try to make sense of it all: is the business doing well, is the price justified, and what could change that?

An agent needs those sources too. A general web summary can give it context, but the revenue number, the risk disclosure, and the price timestamp should come from evidence it can identify.

In this guide, we will connect SEC filings, market and company data, and economic indicators to an existing TypeScript agent using Valyu's AI SDK. Then we will use financial DeepResearch workflows when the job calls for a complete, repeatable research pack.

What is domain-grounded financial retrieval?

Domain-grounded financial retrieval gives the model financial records that fit the question: filing passages for disclosures, structured data for prices and statements, and economic series for macro context. Valyu retrieves those sources. Your model still needs to align companies, reporting periods, currencies, and timestamps before drawing a conclusion.

The working pattern is:

1. Add the three financial search tools

• Use @valyu/ai-sdk for tools that plug into Vercel AI SDK.

• Use valyu-js for the underlying Search API, catalogue discovery, and DeepResearch workflows.

Set VALYU_API_KEY in your server environment, using a key from platform.valyu.ai. Keep your model provider's existing configuration. The OpenAI package above is the adapter's declared peer; the function receives the compatible AI SDK model you already use.

Here is the core integration:

import { generateText, stepCountIs, type LanguageModel } from "ai";
import { secSearch, financeSearch, economicsSearch } from "@valyu/ai-sdk";
export async function researchFinance(model: LanguageModel, prompt: string) {
  return generateText({
    model, prompt,
    tools: { secSearch: secSearch({ maxNumResults: 3 }),
      financeSearch: financeSearch({ maxNumResults: 3 }),
      economicsSearch: economicsSearch({ maxNumResults: 3 }) },
    stopWhen: stepCountIs(5),
  });
}

Pass your existing model and research question to researchFinance. The result contains generated text and intermediate steps, including tool results.

These functions are tool factories, not standalone searches.

Calling secSearch() creates a tool definition. The AI SDK executes it when the model makes a tool call and feeds the result back into the conversation.

The model chooses tools per question; registering three tools does not force three searches every time. stepCountIs(5) bounds the generation loop's steps, not total dollar spend. maxNumResults limits results per tool request.

2. Know which financial data you can add

The tools provide convenient default source baskets. They do not enable every dataset automatically. Use includedSources to choose additional datasets your account can access.

The following source families are listed in the current data catalogue and finance guide:

For example, expose separate fund, valuation, and macro tools with explicit sources:

export const marketTools = {
  funds: financeSearch({ includedSources: ["valyu/valyu-etfs", "valyu/valyu-funds"] }),
  valuation: financeSearch({ includedSources: ["valyu/valyu-statistics-US"] }),
  macro: economicsSearch({ includedSources: ["valyu/valyu-bls", "valyu/valyu-fred", "valyu/valyu-worldbank-indicators", "valyu/valyu-imf"] }),
};

Register whichever of these tools your agent needs in generateText's tools object. The configuration replaces that helper's source list; it does not grant dataset access.

The finance guide also names an earnings-calendar dataset. It was not present in the live catalogue check for this article, so it is not assumed in these examples. Confirm calendar availability in your organisation before building around it.

For current events, the adapter's webSearch tool can add news context. Its companyResearch tool provides synthesised company intelligence. Keep reported figures traceable to the underlying records rather than treating a summary as a filing. Wiley Finance can add research methods and book chapters where rights permit.

3. Use filings and market records for different parts of the question

Use filings for what the company disclosed:

• 10-K: annual business, financials, risk factors, and management discussion.
• 10-Q: quarterly reporting and updates.
• 8-K: material events and associated disclosures.
• 13F-HR, Schedule 13D/13G: institutional holdings and beneficial-ownership disclosures.
• S-4, DEF 14A, and other forms: transaction and proxy-related material.

Name the company, form, fiscal period, and section in the query. “Apple FY2025 10-K Item 1A risk factors” is easier to evaluate than “tell me about Apple.” Use structured statement or statistics datasets when the task needs a numeric comparison.

Then give the model a clear research task:

Research Microsoft using its FY2025 10-K, current valuation records, and US interest-rate data. Separate the reporting period from each market-data timestamp. Compare the disclosed risks with the relevant financial metrics. Cite original source URLs, show currencies and units, and identify missing evidence rather than filling gaps.

Before the final brief, the agent should:

1. Match the issuer. Confirm the entity and ticker rather than joining similarly named companies.
2. Align the period. Fiscal year, calendar year, quarter, and trailing-twelve-month figures are different.
3. Preserve units and timestamps. Distinguish dollars from millions of dollars, reported currency from FX conversions, and a quote time from a filing date.
4. Separate disclosure from inference. A management statement, structured record, and model interpretation should remain identifiable.
5. Keep the source links. Review the tool results and support for each cited conclusion.

An important API detail: a search result's price is its retrieval charge, not the stock price. Financial values belong in the returned financial content. Likewise, relevance scores measure query match, not investment attractiveness.

The adapter helpers do not expose every lower-level Search option.

For enforced publication-date filters, use valyu-js Search with startDate/endDate in a custom tool. A date in the prompt alone is not a point-in-time or backtesting guarantee.

4. Use DeepResearch for the sources and investigations beyond a lookup

Several financial research sources are DeepResearch-only, not directly searchable datasets:

The documented sanctions coverage includes OFAC SDN and consolidated lists, UN, UK HMT, Swiss and Australian sanctions, INTERPOL, and US CSL. Check the current catalogue and access rules for the particular source. Do not pass DeepResearch-only IDs to the three Search helpers and assume they will work.

For IP context, US and European patent datasets are directly searchable, but they are patent evidence rather than financial statements. Source choice follows the research question.

5. Reuse financial DeepResearch workflows

A workflow packages a research process: prompt variables, source strategy, recommended mode, tools, output instructions, and deliverables. You supply the changing company, ticker, sector, or period. Running it creates a normal asynchronous DeepResearch task.

There are prebuilt financial workflows across private equity, hedge funds, investment banking you can access via Valyu Search API.

Related consulting templates include con-market-sizing, con-industry-primer, con-competitor-benchmark, and con-pricing-benchmark. They can support market sizing and commercial research. Read their declared variables rather than reusing a financial template's keys.

Discover them with valyu.workflows.list(), inspect a chosen template with get(), and preview it before starting the billed run. Curated workflows are read-only; organisations can also create private templates.

Preview a company-profile workflow

import { Valyu } from "valyu-js";
export const valyu = new Valyu();
export async function previewCompany(company: string) {
  const profile = await valyu.workflows.get("ib-company-profile");
  if (!profile.success || profile.workflow?.version == null) throw new Error("Workflow unavailable");
  return valyu.workflows.preview("ib-company-profile", {
    workflowParams: { company }, workflowVersion: profile.workflow.version,
  });
}

Call previewCompany("NVIDIA (NVDA)"). Check success, then inspect the resolved mode, tools, and deliverables. The live preview for this guide returned XLSX and DOCX deliverable types. Previewing resolves the template without running research or spending research credits.

Run the inspected version

export async function runCompanyWorkflow(company: string, version: number) {
  const task = await valyu.deepresearch.create({
    workflowId: "ib-company-profile", workflowParams: { company }, workflowVersion: version,
    tools: { code_execution: true },
  });
  if (!task.success || !task.deepresearch_id) throw new Error("Could not start research");
  return task.deepresearch_id;
}

Pass the same company and the version from the preview's workflow field. This starts a billed task and returns its ID. Save that ID, then poll status, use deepresearch.wait(), or collect the result through a webhook.

Excel, Word, and PowerPoint deliverables require code execution. The example enables it explicitly. Its total can exceed the mode's base charge because tools and extra deliverables can add costs. The supported deliverable types are CSV, XLSX, DOCX, PPTX, and PDF; each file has its own generation status.

Do not combine workflowId with a freeform query, researchStrategy, or reportFormat. The template supplies those fields. Pin the version so template changes do not silently change the process; live data can still change the result.

Production Apps built with Valyu Search

If you want to see these integrations in a finished product, try these two apps:

1. Valyu Finance

finance.valyu.ai is a financial research interface with selectable research depth, chart generation, code execution, and deliverables. Its workflow library covers investment banking, private equity, hedge funds, and sales research, with examples such as company profiles, investment committee memos, and long-thesis reports.

It is a useful reference for turning financial retrieval and research workflows into an interface where users can choose the investigation they need.

2. Consult Ralph

Consult Ralph uses Valyu DeepResearch for company research, market analysis, competitive intelligence, and due diligence. Its interface offers PowerPoint, Excel, Word, and PDF deliverables, alongside research history and completed example reports.

This is a useful example of taking the same research infrastructure beyond an answer box: the output becomes a report, workbook, or presentation that someone can use in their next meeting.

Frequently asked questions

Are secSearch, financeSearch, and economicsSearch part of valyu-js?

They are tool factories from @valyu/ai-sdk, used with Vercel AI SDK. valyu-js is the client for lower-level Search calls, source discovery, and DeepResearch workflows.

Does financeSearch include every financial dataset by default?

No. It has a default source basket. Add specific datasets through includedSources when you need funds, valuation metrics, IMF data, or other eligible sources. Access remains account-dependent.

Can I search fund letters or short-seller reports directly?

Those sources are documented as DeepResearch-only. Use a research task or suitable workflow instead of treating their IDs as ordinary Search datasets.

Is a workflow preview a paid research run?

No. A preview resolves the template. Calling deepresearch.create starts the billed task. Inspect the mode, tools, and deliverables before running it.

Does the SDK automatically validate a financial conclusion?

No. The tools retrieve evidence, and the model uses it. Period alignment, unit handling, source support, and any calculations still need checks in your agent workflow.

What to build next

Start with the three financial tools and a narrowly scoped company question. Add source-specific tools as needed. Use a financial workflow when the output is a recurring earnings pack, diligence memo, valuation reference, or research workbook.