Introducing Deep Agents
Hey, this is Lance from Langchain. So, deep agents is a simple open-source agent harness that implements a few ideas we've seen across many popular agents like Manis, like cloud code, notably planning, computer access, and subent delegation. So, this open source harness bakes in these tools for you, but is easily extendable. You can provide custom prompts, you can provide custom tools, and it's all open source. You can modify it any way you want.
Now to help people get started with different applications of deep agents, we created this deep agent quick start repo which has a number of folders for different use cases starting with research because we've done so much on research already. It's such a popular use case that I want to showcase it.
Demo: The Research Agent in Action
So first I'm going to show this running and then I'm going to walk through everything that's happening under the hood. So here's a deep a so here's a UI that we built custom for deep agents. I have this running locally. Submit my research request. Run. And so we can see research finishing up here. And so our deep agent research task finished.
Now what you see here are all the different tool calls that are made throughout the trajectory. You can open each of these up. You can look at the arguments of the tool call. You can see it follows this trajectory of tool calls. It gives us a summary of what it's done. We can open up any files it generated. And here is the final report that it generated for us. Nicely cited. And when you look at this trajectory, you see a bunch of different tool calls. Write file, write to-dos, tavly search, think tool, read file, write to-dos. What are these? Where are they coming from? What's kind of going on under the hood here. So, let's talk about that a little bit.
In the repo, you can see here there's a list of folders. In this case, only one. We only have a single quick start for research. And this is built on top of the deep agents package. And you can see that repo here, lane chain deep agents. And if you scroll down in the readme, there's something that's very simple and important to understand. With every deep agent, you have a few built-in tools that you can use. A planning tool, sub aent delegation tool, various file system tools, as well as any tools you provide or instructions you provide.
So this table lists all the different built-in tools that you get with DB agents out of the box. And we can see that these tool names are identical to what we saw in that agent trajectory. Write to-dos, read to-dos, list files, read file, write file, edit file, glob grip, execute shell commands, and a task tool to de delegate out work to sub aents. Now, this simple set of atomic tools allow you to do a very large number of things because it lets you interact with a file system, call shell commands, plan through to-dos, delegate tasks through this task tool.
And you'll recognize that these tools are quite similar to what you see when you're using Manis or using cloud code that similarly have access to a file system. In the case of cloud code, typically it's your local file system. In the case of Manis, it's a sandbox, have sub aent delegation tools, and have the ability to plan. These are the fundamental things that we see that are very important for building longunning agents capable of handling complex tasks.
So now that you understand the fundamental tools that are baked into deep agents package, quick starts is pretty easy to follow. If we open up the deep research quickart directory and so I'm in the readme for the deep agents quickart and what's nice is you can interact with this quick start a few different ways. You can just simply run a Jupyter notebook which I'll show you right now or you can run langraph server locally and connect it to a UI like for example the UI we were looking at previously. I'll show that a bit later.
So, first let's just kick this off. You can run this command in your terminal from this directory. Spin up a notebook. So, here it is. Notebook's running. And the way think about any of these quick starts is four different things. First, understand the native tools available to you when using deep agents. We just talked through that. That's a table of tools I showed in the readme. And then for any given use case, you want to supply a few different things. Any task specific tools, task specific instructions or task specific sub aents. Now for research, I'm going to supply two different specific tools. One is a search tool, the other is a think tool. The search tools can be used to search for relevant URLs to my query and then fetch the full web page contents. Pretty intuitive. A think tool is completely optional. I tend to like it for auditing. It's just a tool that the agent can call that enforces interle thinking. Now note that some SDKs like claude have this built in but it's not always the case. So this think tool is a nice way to explicitly tell the agent to think between steps and you can instruct it accordingly when to call the think tool. So it's very useful for auditing the agent trajectory and what it's doing at different points in time. But of course completely optional. You don't have to use it. I just tend to like to.
And if you look at the readme in that deep research folder, look at the research agent folder. The tools are defined right there in this tools.py. This is a very simple search tool defined here using Tavali search API. But you can use any search API you want and again a think tool which doesn't actually do anything. And this is important to note. It just forces the agent to pause and produce a reflection. So I import those tools. We have them available.
Customizing Your Agent: Prompts & Sub-Agents
Now, this is the part that often is the most important and can be quite tricky. Taskm instructions. Of course, prompting is not dead. It's still very much alive and very important with agents.
Here, I added a few tips that I tend to like and I've used in the past for prompting agents for tastic research. I got this from a video that was really nice from some folks at Anthropic. Think like the agent. In this particular case, what instructions would you give a new colleague related to research task? Read the question carefully. Start with broad searches. Pause and pause and assess. Use narrower searches to gather information. So just some heristics about how to perform research.
Now this one I found to be very important from some prior work and research. Heristic to prevent spin out. So stop when you can answer correctly. Give budgets for the number of tool calls that you wanted to per perform at maximum. Give it limits. Always stop after some number of tool calls. I've seen cases where the agent will continue doing searches to refine its result without stopping. And so these heristics can be very helpful for preventing spin out as you might call it, which just means continuing to make tool calls to search for further and further information long after you've collected enough information to actually answer the question.
And I ask NIS agent to show its thinking. And again, I use that think tool to enforce it. And again [clears throat] looking at the repo, the prompts I all check in here in this prompts.py. And again, you can modify these any way you want. Of course, this is just a starting point that I found to be pretty useful. I import the prompts here. We can look at them. So they follow the heristics I talked about above. These are instructions for the researcher. For example, I tell it the available tools. I give it instructions, you know, think like a researcher with limited time. I give it budgets. I ask it to show its thinking. And I provide some final response formatting in my instructions.
Now, one other thing that's nice about deep agents is you can supply custom sub agents. So, remember deep agents has that task tool that can use to delegate tasks to sub agents. Now, why do we do this? This is actually very useful for context isolation. The main idea is simply that a research task can be really tokenheavy and if you want to research a particular question, you can delegate that out to sub agent. it can go off and do a bunch of searches, learn a bunch of information, pass that result back to your main agent as a result. So, it's a really nice way to compartmentalize or isolate all the context collected in that research task in the isolate context window of the sub agent and just return the result. So, that's why these sub aents are really nice particularly for research. In this case, I can just initialize one. It's just a dictionary. Deep agents accepts this. Give it a name, give it a description, and I give it some instructions. So, whenever this stub agent spawns, it receives the researcher instructions, and I give it the tools.
I can put this all together into some general workflow instructions. So, this is what the overall deep agent will receive in terms of how to conduct research, sub aent delegation instructions, when to delegate to sub agents, and the researcher instructions, again, how to perform research. And I can show this consolidated prompt. And in these workflow instructions, I'm actually going to tell the agent to use its native tools occasionally. Remember, that's why it's very important to actually understand the native tools built into deep agents for you. In this case, I want to remember the user's research request. So, I'm going to have the deep agent call its write file tool to save the research request to this file research request. MD. I'm going to tell it to use its to-do list tool to write to-dos to break down the research task. I'm going to tell it to use its task tool to delegate research and I'm going to have it write a fun report. And I'll reinforce some report lighting guidelines here. And I provide some rules here for sub aent delegation because I found that elements can be a little bit too eager with sub aent delegation and spawn like five different sub aents for things that really can be grouped into a single sub aent call. So I do think it's important to lay out a crisp delegation strategy for your use case. And then finally the research instructions themselves.
Initializing the Agent & Understanding Middleware
Now once you have those things defined actually initializing the deep agent is trivial. From deep agents you import create deep agent you pass the model you want to use. You pass the tools you pass the instructions and you pass any custom sub agents. And now the nice thing here is deep agents is abstracting only a few things. in particular to distracting a set of built-in default atomic and very general tools that we found to be useful across many applications notably what I just showed task tool for subage delegation to-do list file system operations. those things are very general you want them across many different age applications you don't want to reimplement them every time for each agent you're building so it's baked into the harness for you but it's very important to think through your prompting your sub aents and of course whatever custom tools you.
So we add them all here. We show this. Now this middleware thing is kind of odd, right? Like what is all this? So middleware is just what we use in Langraph to help orchestrate the agent loop. Remember an agent loop is very simply an LM calling tools in a loop. But you often want stop at particular points in this loop and do different things.
Middleware can serve as hooks. stopping for example before the agent before the model before tools are called. So at different points in this agent loop you can inject middleware to stop and do something. Now not only that middleware can also provide tools and so in particular in the readme for deep agents I've added a table that shows you for every tool what middleware provides it.
A Deeper Dive into Middleware
So you can kind of think about file system middleware as providing a tool set to the agent and this is a list of all the middleware that's used under the hood with deep agents. So again it has to-do list middleware that provides the task related tools right here file system middleware sub aent middleware for delegation those are all pretty obvious those are kind of acting as tool sets but also middleware can act more as like hooks.
So we have this summarization middleware. This auto summarizes whenever the context exceeds 170,000 tokens and this is configured for enthropic models. You can tune this for other models if you need and this is acting in the same way that compaction works in for example cloud code. Prompt caching middleware is built in which is available with anthropic only. We have this patch tool calls middleware which fixes dangling tool calls. And we have human loop middleware which can pause execution for human approval at different steps.
And so the way to think about this is this middleware is acting at different points in this agent life cycle doing different things. Not only can it basically serve tools to the agent like we see with for example file system middleware but it can also do things like summarization as you can see before the model. We summarize the message history if it exceeds a token limit. And you can read more about middleware in our documentation which I'll link in the video description.
Running the Agent and Tracing with Langsmith
Now we can run this in our notebook and now you understand where the different tools are coming from and the instructions we've given their agent. So you can see that when I kick off this process because the instructions I've given it, it's going to write the user's request to a file using its write file tool. It's also going to write to it's going to use its write to-dos tool to create a bunch of research to-dos.
Now I want to call something out important here. When you see this write file tool call and you see this file path, what's going on here? Is this writing to your file system or what? So actually by default deep agent it will only write to an internal inmemory state object. What's really nice is deep agent is built on langraph. Langraph has this notion of a state object and so it can write these files to state and then read them back from state. Now that will persist in memory during the course of the agent execution. But deep agent does support different backends. If you want to access a file system, you can easily do that. So by default, it'll just use its in-memory state object for file reading and writing and manipulation. But it can also use different backends like a sandbox or like a local file system. So again, I'll share that in the video description and provide documentation on different backends if you want to try that.
We can see after it writes its to-dos, after it writes its file, it'll call its task tool. This will kick off a research agent and it's initialized with description of a research task which is great. And we can see we now get the outputs of all those tool calls. We updated a file. We updated to-dos and this is the output of the sub aent. So you can see the sub aent returns its entire research output back to the parent which is great. We can see it's very extensive deep dive, very nice, well sourced, everything we would want.
We update our to-dos. We then write a file final report.md based upon all the result all the research done by the sub agent which is great update the todo list to note that we have completed our task the file is written we do a verification to confirm the report addresses the original question which we have saved you can see right here we can read that research request file to confirm that a report actually addresses it and then what's nice is all these file reading and write operations are all happening within the langraph state object all in memory, but you can pull it back into the context window of the LM very easily from the state object. So you can really think about this as a way of performing recitation. Write the request to state, do a bunch of stuff, then read it back in to make sure you've actually addressed the request. This is a very nice trick that actually Manis talks about quite a bit to steer agents and ensure they stay on track. And the final verification is done. The agent returns quick summary of what it's learned and the final report is of course saved to the langraph state object.
Because we're using Langraph under the hood, of course, this is all traced to Langsmith. You can open up Langsmith and open up the trace and you can look at all those individual tool calls if you want as well as all the different model calls. You can see we're using clonet cla and this is the entire researchation trajectory that we all have saved and logged for us in Langmith.
Deploying the Agent with LangGraph Server
And that shows you how to run this entire process in a notebook which is quite nice for interactive inspection of prompts. Now if you want to run this as a deployable application, you can just very simply run langraph dev just like this. That spins up a langraph server.
Now the server has this built-in interface called studio which you can use to run the agent. And the readme also has instructions for connecting it to connecting this local deployment up with deep agent UI. That's all right here which we worked with right here. So again the what's happening here is I have the deep agent quick starts repo. I have the directory which has the deep research example. I ran langraph dev in that directory that spun up a local langraph server. And then I just connected it with this UI. That's it. And then I can interact with graph server which encapsulates my agent using this UI which allows me to very nicely visualize the files that it generated.
Conclusion and Next Steps
So if you pull all the way back out, what's going on here? Deep agents is an open source agent harness that features a number of commonly used tools for planning, for computer access, for sub aent delegation. We see these tools used across many agent applications. Manis uses them, cloud code uses them. So they're very common atomic powerful tools. Deep agents implements them for you and you can easily adapt it for your use case with custom tools, custom instructions, custom sub agents.
Deep agent quick start then built built upon the deep agents package and has some nice out of the box agent and has some nice out of- the box examples starting with research because it's such a popular one. We've done so much on it. Again, you can check that research readme that shows you how to for example run it very quickly in a notebook as well as a local graph server which connect to a UI. All the code necessary is right in here. You for example just prompts and tools we provide for the research task and the agent itself is initialized in this script as well as in a notebook which we saw right here.
The key point to keep in mind is deep agents is very general. It's easily adaptable for a given use case. Prompting and tool definition are really the things you need to think about quite a bit. And it's very important to understand the base capabilities and tools built into the harness so you can adapt it. And that's what we really tried to explain in the quick start readme by laying out down here all the built-in components within deep agents that you need to understand in order in order to best make use of it. So hopefully this was a useful overview. We're going to be adding to this repo. If you have specific examples you want added, feel free to just comment in the video. We can get to them. And it's all open source as well. Also feel free to just contribute directly. Thanks a lot.
