Agent Map

agent_map runs one web research agent per row of a DataFrame, in parallel. Each agent searches the web, reads pages, and returns structured results that populate new columns. The transform is live web research: agents fetch and synthesize external information per row.

For a single question, or to generate a list from scratch, use multi_agent instead.

single_agent is deprecated. Use multi_agent for a single question.

Examples

Every operation is a coroutine. Run it with asyncio.run() as below, or await it directly in a Jupyter notebook. Later snippets on this page omit the wrapper for brevity.

agent_map

import asyncio

from pandas import DataFrame
from futuresearch.ops import agent_map

companies = DataFrame([
    {"company": "Stripe"},
    {"company": "Databricks"},
    {"company": "Canva"},
])


async def main():
    result = await agent_map(
        task="Find the company's most recent annual revenue",
        input=companies,
    )
    print(result.data.head())


asyncio.run(main())

Each row gets its own agent that researches independently.

Response model

agent_map supports structured output via a custom Pydantic model.

from pandas import DataFrame
from pydantic import BaseModel, Field
from futuresearch.ops import agent_map

companies = DataFrame([
    {"company": "Stripe"},
    {"company": "Databricks"},
    {"company": "Canva"},
])

class CompanyFinancials(BaseModel):
    annual_revenue_usd: int = Field(description="Most recent annual revenue in USD")
    employee_count: int = Field(description="Current number of employees")
    last_funding_round: str = Field(description="Most recent funding round, e.g. 'Series C'")

result = await agent_map(
    task="Research each company's financials and latest funding",
    input=companies,
    response_model=CompanyFinancials,
)
print(result.data.head())

The output now has annual_revenue_usd, employee_count, and last_funding_round columns.

Parameters

Name	Type	Description
`task`	str	The agent task describing what to research for each row
`input`	DataFrame \| UUID \| TableResult	The rows to research
`session`	Session	Optional, auto-created if omitted
`effort_level`	EffortLevel	LOW, MEDIUM, or HIGH (default: MEDIUM). Mutually exclusive with the custom knobs below; set it to `None` to use those instead
`response_model`	BaseModel	Optional schema for structured output. With `return_table=True`, describe a single item and the worker wraps it in a list
`llm`	LLM	Model for each row's agent. Required when `effort_level` is `None`
`iteration_budget`	int	Agent iterations per row, 0 to 20. Required when `effort_level` is `None`
`include_reasoning`	bool	Include reasoning notes. Required when `effort_level` is `None`
`document_query_llm`	LLM	Model for the document-query tool that reads scraped web pages. Defaults to the system default
`return_table`	bool	If True, each row's agent emits a list of records and the result has one row per item, with an `_expand_index` column. Output rows can exceed input rows. Default: False
`enforce_row_independence`	bool	If True, each agent runs fully independently: no adaptive budget adjustment and no straggler management, so no row is hurried or limited based on another's progress. Use when consistent per-row behaviour matters more than throughput. Default: False
`extra_notification_text`	str	Text appended to every inter-iteration notification the agent receives. Useful for nudging behaviour across all steps without changing the task prompt
`agent_harness`	AgentHarness	Run each row through the Claude or OpenAI agent SDK instead of the native ReAct loop. Not enabled for all accounts; the server rejects requests it does not accept

Effort levels

The effort level controls how thorough the research is on each row.

LOW: a single LLM call, cheapest and fastest
MEDIUM: multiple sources consulted (default)
HIGH: deep research, cross-referencing sources, higher accuracy

Via MCP

MCP tool: futuresearch_agent

Parameter	Type	Description
`csv_path`	string	Path to input CSV file
`task`	string	What to research for each row

Related docs

Guides

Add a Column with Web Lookup

Reference

multi_agent for a single question or to generate a list

Agent Map

For a single question, or to generate a list from scratch, use multi_agent instead.

single_agent is deprecated. Use multi_agent for a single question.

Examples

Every operation is a coroutine. Run it with asyncio.run() as below, or await it directly in a Jupyter notebook. Later snippets on this page omit the wrapper for brevity.

agent_map

import asyncio from pandas import DataFrame from futuresearch.ops import agent_map companies = DataFrame([ {"company": "Stripe"}, {"company": "Databricks"}, {"company": "Canva"}, ]) async def main(): result = await agent_map( task="Find the company's most recent annual revenue", input=companies, ) print(result.data.head()) asyncio.run(main())

Each row gets its own agent that researches independently.

Response model

agent_map supports structured output via a custom Pydantic model.

from pandas import DataFrame from pydantic import BaseModel, Field from futuresearch.ops import agent_map companies = DataFrame([ {"company": "Stripe"}, {"company": "Databricks"}, {"company": "Canva"}, ]) class CompanyFinancials(BaseModel): annual_revenue_usd: int = Field(description="Most recent annual revenue in USD") employee_count: int = Field(description="Current number of employees") last_funding_round: str = Field(description="Most recent funding round, e.g. 'Series C'") result = await agent_map( task="Research each company's financials and latest funding", input=companies, response_model=CompanyFinancials, ) print(result.data.head())

The output now has annual_revenue_usd, employee_count, and last_funding_round columns.

Parameters

Name

Type

Description

task

str

The agent task describing what to research for each row

input

DataFrame | UUID | TableResult

The rows to research

session

Session

Optional, auto-created if omitted

effort_level

EffortLevel

LOW, MEDIUM, or HIGH (default: MEDIUM). Mutually exclusive with the custom knobs below; set it to None to use those instead

response_model

BaseModel

Optional schema for structured output. With return_table=True, describe a single item and the worker wraps it in a list

llm

LLM

Model for each row's agent. Required when effort_level is None

iteration_budget

int

Agent iterations per row, 0 to 20. Required when effort_level is None

include_reasoning

bool

Include reasoning notes. Required when effort_level is None

document_query_llm

LLM

Model for the document-query tool that reads scraped web pages. Defaults to the system default

return_table

bool

If True, each row's agent emits a list of records and the result has one row per item, with an _expand_index column. Output rows can exceed input rows. Default: False

enforce_row_independence

bool

If True, each agent runs fully independently: no adaptive budget adjustment and no straggler management, so no row is hurried or limited based on another's progress. Use when consistent per-row behaviour matters more than throughput. Default: False

extra_notification_text

str

Text appended to every inter-iteration notification the agent receives. Useful for nudging behaviour across all steps without changing the task prompt

agent_harness

AgentHarness

Run each row through the Claude or OpenAI agent SDK instead of the native ReAct loop. Not enabled for all accounts; the server rejects requests it does not accept

Effort levels

The effort level controls how thorough the research is on each row.

LOW: a single LLM call, cheapest and fastest

MEDIUM: multiple sources consulted (default)

HIGH: deep research, cross-referencing sources, higher accuracy

Parameter

Type

Description

csv_path

string

Path to input CSV file

task

string

What to research for each row