How to build your first
deep agent

Let me show you what I mean by a "shallow" agent. Here's the kind of meeting prep agent you might build with a typical agent framework:

1def prepare_for_meeting(person_name: str, company: str):
2    """A shallow agent with a fixed workflow."""
3 
4    # Step 1: Always search LinkedIn
5    person_info = search_linkedin(person_name)
6 
7    # Step 2: Always search company info
8    company_info = search_company(company)
9 
10    # Step 3: Always search recent news
11    news = search_news(company)
12 
13    # Step 4: Generate summary
14    return generate_summary(person_info, company_info, news)

This works fine - until it doesn't. What if the person isn't on LinkedIn? What if the meeting is internal and you don't need company research? What if you find conflicting information and need to dig deeper? The workflow can't adapt for these situations.

Deep agents are different. They can plan their approach, decide what to investigate based on what they find, and adapt when things don't go as expected. Here's what makes them work:

• Planning tools - a todo list that helps the agent track progress across long tasks
• Sub-agent delegation - the ability to create specialised agents for specific subtasks
• Filesystem access - a workspace where agents can store notes and accumulated context
• Automatic context management - summarises conversation history when it gets too long

These might sound simple, but the combination is surprisingly effective. Let's build up our meeting prep agent step by step, adding each capability and seeing how it improves the result.

If you've used LangChain before, you might be wondering how Deep Agents fits alongside LangGraph. Both were created by the same company, but they serve different purposes.

LangGraph gives you complete control over your AI agent and how it should approach a task. You can define the nodes, edges, and state transitions manually. This is really useful when you need to develop custom, repeatable workflows.
For example, an ordering system where each step - payment, inventory check, shipping - requires a specific state change and support for rollback.

Deep Agents is much more flexible. It allows you to create an agent that can plan, use tools, delegate to sub-agents, and manage its own context. It's well-suited for longer, more complex tasks and when you can't predict the exact workflow of your users.
For example, a research assistant that searches the web, decides what to investigate next based on what it finds, and can dig deeper if it doesn't have enough information - without you having to define every step in advance.

Generally, I'd advise that you start with Deep Agents. If you find you need greater control over the process and what tools the agent calls, you should use LangGraph instead. But most agent use cases - research, coding assistants, data analysis - are a natural fit for Deep Agents.

Let's start with the simplest possible deep agent. First, install the package:

1pip install deepagents tavily-python

Then create a .env file with your API keys:

1# Use one of these (Anthropic is my recommendation)
2ANTHROPIC_API_KEY=your-anthropic-key
3# OR
4OPENAI_API_KEY=your-openai-key
5 
6# Required for web search
7TAVILY_API_KEY=your-tavily-key

We'll now create a basic agent, which can search the web and help us prepare for upcoming meetings.

1from deepagents import create_deep_agent
2from tavily import TavilyClient
3import os
4 
5# Set up Tavily for web search
6tavily = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
7 
8def web_search(query: str):
9    return tavily.search(query, max_results=5)
10 
11# Create our meeting prep agent
12agent = create_deep_agent(
13    tools=[web_search],
14    system_prompt="""You are a meeting assistant. When given
15details about an upcoming meeting, research the attendees and their company
16- so that the user can be better prepared.
17 
18Be thorough - if you can't find information through one approach, try another.
19Focus on information that will ensure the meeting goes well.""",
20)
21 
22# Prepare for a meeting
23result = agent.invoke({
24    "messages": [{
25        "role": "user",
26        "content": "I have a sales call tomorrow with Sarah Chen, VP of Engineering at DataFlow Inc. Help me prepare."
27    }]
28})
29 
30print(result["messages"][-1].content)

Even this basic version is more capable than the shallow agent we saw earlier. The agent can decide what to search for, change its approach if it doesn't find what it needs, and combine information from multiple searches.

The basic agent works fine, but it will struggle with complex, long-running tasks - the agent can jump between topics randomly, forget what it's already searched for, or miss important areas entirely.

By using the built-in planning tools, we can keep our AI agent on-track when it's faced with difficult work. The agent will write todos, track what it needs to research, and then mark them complete as it progresses.

1agent = create_deep_agent(
2    tools=[web_search],
3    system_prompt="""You are a meeting assistant.
4 
5Before starting research, create a todo list of what you need to find out:
6- Background on the person (role, experience, recent work)
7- Company information (what they do, recent news, competitors)
8- Potential talking points and questions to ask
9 
10Work through your list systematically. Mark the items as complete when you finish them.
11If you discover something important that needs more investigation, add it to your list.""",
12)

The planning tools (write_todos and read_todos) are automatically available - you just need to tell the agent to use them in the system prompt.

This might seem trivial - it's just a todo list. But I was surprised by how much it improves the agent's behaviour. When the agent explicitly writes down what it's trying to do, it stays more focused and makes better decisions about what to do next.

When the agent researches multiple people or a complex topic, it accumulates a lot of context. Search results, company profiles, news articles - it all adds up. Eventually, you'll hit the model's context limit.

Deep Agents solves this with filesystem tools. The agent can save research notes to files as it goes, keeping its "working memory" focused on the current task.

1agent = create_deep_agent(
2    tools=[web_search],
3    system_prompt="""You are a meeting preparation assistant.
4 
5As you research, save your findings to files:
6- Save person research to /notes/person.md
7- Save company research to /notes/company.md
8- Save your final briefing to /output/briefing.md
9 
10This keeps your context clean and lets you handle larger research tasks.
11When you're done, read back your notes to create a final summary.""",
12)

The filesystem tools (write_file, read_file, ls) are built-in, just like the planning tools. The agent can create directories, write notes, and read them back when needed.

There's also automatic context management happening behind the scenes. When the conversation exceeds about 170,000 tokens, the framework automatically summarises earlier parts to make room for new content.

For our meeting prep agent, we're doing two different things: deep research and writing a briefing document. These require different approaches - research needs to be thorough and exploratory, while the briefing needs to be concise and actionable.

Sub-agents let us split these into specialised roles. The key benefit isn't just separation of concerns - it's context isolation. All the intermediate search results stay in the research sub-agent's context. The main agent only sees the final summary.

1# Research sub-agent - digs deep
2research_subagent = {
3    "name": "researcher",
4    "description": "Conducts in-depth research on people and companies",
5    "system_prompt": """You are an expert researcher preparing for business meetings.
6Research thoroughly by searching multiple sources and cross-referencing information.
7If something seems important, investigate further.
8Return a structured summary of your findings.""",
9    "tools": [web_search],
10}
11 
12# Briefing sub-agent - creates the final document
13briefing_subagent = {
14    "name": "briefing_writer",
15    "description": "Creates clear, actionable meeting briefing documents",
16    "system_prompt": """You create one-page meeting briefing documents.
17Structure: Key facts > Talking points > Questions to ask > Things to avoid
18Be concise and actionable - this will be read right before the meeting.""",
19    "tools": [],  # No tools needed - just writing
20}
21 
22# Main agent coordinates the work
23agent = create_deep_agent(
24    tools=[web_search],
25    subagents=[research_subagent, briefing_subagent],
26    system_prompt="""You are a meeting preparation coordinator.
27 
28For each meeting prep request:
291. Delegate person research to the researcher sub-agent
302. Delegate company research to the researcher sub-agent
313. Give all findings to the briefing_writer to create the final document
324. Review and deliver the briefing""",
33)

Now when the main agent delegates research, all those search results and intermediate steps stay in the researcher's context. The main agent only sees the final summary, keeping its context clean and focused.

Web search is useful, but our meeting prep agent could be much more effective with access to internal systems. Let's add tools to check our CRM for past interactions and look up calendar availability.

1from langchain_core.tools import tool
2 
3@tool
4def get_crm_history(person_email: str) -> str:
5    """Look up past interactions with this person in our CRM."""
6    # In practice, this would query your CRM API
7    # Returns: past meetings, emails, deal history, notes
8    return "CRM lookup results for " + person_email
9 
10@tool
11def check_calendar(date: str) -> str:
12    """Check calendar availability for a given date."""
13    # Would integrate with Google Calendar, Outlook, etc.
14    return "Calendar availability for " + date
15 
16@tool
17def send_briefing_email(to: str, subject: str, body: str) -> str:
18    """Send the meeting briefing via email."""
19    # Email sending logic
20    return "Briefing sent to " + to
21 
22# Add custom tools alongside web search
23agent = create_deep_agent(
24    tools=[web_search, get_crm_history, check_calendar, send_briefing_email],
25    subagents=[research_subagent, briefing_subagent],
26    system_prompt="""You are a meeting preparation coordinator.
27 
28You have access to:
29- Web search for public information
30- CRM to check past interactions with this person/company
31- Calendar to check availability
32- Email to send the final briefing
33 
34Always check the CRM first - past interactions are more valuable than web research.""",
35)

The @tool decorator tells the framework how to present each function to the AI. The docstring becomes the tool's description, so write it clearly - this helps the agent understand when to use each tool.

You meet with some people regularly - quarterly business reviews, ongoing client relationships, recurring team syncs. It would be wasteful to re-research them from scratch every time.

Deep Agents supports persistent storage, so the agent can remember past research and build on it.

1from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
2from langgraph.store.memory import InMemoryStore
3 
4# Create persistent storage (use a database in production)
5persistent_store = InMemoryStore()
6 
7backend = CompositeBackend(
8    default=StateBackend(),  # Working files are ephemeral
9    routes={
10        "/contacts/": StoreBackend(store=persistent_store),  # Contact profiles persist
11        "/meetings/": StoreBackend(store=persistent_store),  # Meeting history persists
12    },
13)
14 
15agent = create_deep_agent(
16    tools=[web_search, get_crm_history, check_calendar, send_briefing_email],
17    subagents=[research_subagent, briefing_subagent],
18    backend=backend,
19    system_prompt="""You are a meeting preparation coordinator with persistent memory.
20 
21Before researching someone new:
221. Check /contacts/ for existing profile
232. Check /meetings/ for past meeting notes
24 
25After preparing a briefing:
261. Update their profile in /contacts/
272. Save meeting prep notes to /meetings/
28 
29Build on past knowledge rather than starting from scratch.""",
30)

Now the agent will check for existing information before doing new research. For a recurring client, it might say "I last prepared a briefing for Sarah Chen three months ago. Since then, DataFlow announced a Series B funding round. Let me update the briefing with this new information."

Our meeting prep agent can now send briefings via email. But you probably don't want it sending emails without your approval - what if the research contains something sensitive or incorrect?

Deep Agents has built-in support for human-in-the-loop workflows. You can require approval for specific tools before they execute.

1agent = create_deep_agent(
2    tools=[web_search, get_crm_history, check_calendar, send_briefing_email],
3    subagents=[research_subagent, briefing_subagent],
4    backend=backend,
5    interrupt_on={
6        "send_briefing_email": {
7            "allowed_decisions": ["approve", "edit", "reject"]
8        },
9    },
10    system_prompt="""You are a meeting preparation coordinator.
11 
12Research the attendees, create a briefing, then offer to email it.
13The email will require human approval before sending.""",
14)

Now when the agent tries to send an email, execution pauses and you'll be asked to approve it. You can approve as-is, edit the content first, or reject it entirely.

After building our meeting prep agent step by step, here's what I've learnt about deep agents:

We started with a shallow meeting prep agent that followed a fixed workflow and couldn't adapt. By the end, we had a deep agent that can plan its research, store context in files, delegate to specialised sub-agents, integrate with internal systems, remember past meetings, and require approval before taking action.

That progression - from simple to sophisticated, each step adding clear value - is how I'd recommend approaching any deep agent project. Don't try to build everything at once. Start with basic tools, then add capabilities as you hit their limits.

The meeting prep example is just one application. The same patterns work for research assistants, coding helpers, data analysis, customer support - anywhere you need an agent that can handle complex, unpredictable tasks rather than following a fixed script.

Loop Newsletter

Get weekly AI insights delivered
to your inbox

Subscribe for free

Read by executives at: