May 13, 2026 AgentsLong-runningTools
Build a deep research agent
Run long research jobs with search tools, streamed progress, trace inspection, and completion notices.
This cookbook builds a deep research agent for long-running jobs where progress, durability, and traceability matter more than a single chat response.
Scenario
A user asks for a competitive brief. The agent plans the work, searches the web, reads selected sources, extracts notes, synthesizes a report, and sends a completion notification.
What you build
- A planner step.
- Search and fetch tools.
- Parallel source reading.
- Progress events for the UI.
- A final report artifact.
- A completion notification that is sent once.
Workflow shape
@workflow
async def deep_research(ctx: WorkflowContext, topic: str) -> ResearchResult:
plan = await ctx.step(plan_research, topic)
sources = await ctx.step(search_sources, plan.queries)
notes = await ctx.step(read_sources, sources)
report = await ctx.step(write_research_report, topic, notes)
notification = await ctx.step(send_completion_once, report.artifact_id)
return ResearchResult(report_id=report.artifact_id, notification_id=notification.id)Each long call is isolated. If source reading fails halfway through, completed work can be replayed from the journal.
Progress model
Emit progress from step boundaries rather than from unstructured logs.
{
"phase": "reading_sources",
"completed": 8,
"total": 12,
"run_id": "run_01JRESEARCH"
}The UI can stream these updates while the trace remains the durable record.
Production checks
- Search and fetch outputs are traceable.
- The report stores source citations or artifact IDs.
- Worker restarts do not lose progress.
- Completion notifications are idempotent.
- Failed source reads can be retried without restarting the whole report.