> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: Build a deep research agent
description: Run long research jobs with search tools, streamed progress, trace inspection, and completion notices.
tags: ["Agents", "Long-running", "Tools"]
date: 2026-05-13
last_verified: 2026-05-13
audience: both
---

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

```python
@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.

```json
{
  "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.

## Next steps

- [Build a durable research agent with approval and recovery](/cookbooks/durable-research-agent-approval-recovery.md)
- [Run any AI agent framework on a durable workflow runtime](/cookbooks/bring-your-own-agent-framework.md)
- [Debug AI workflows with traces, not scattered logs](/cookbooks/workflow-native-observability.md)