LangChain Deep Agent 快速入门

1from deepagents import create_deep_agent
2
3agent = create_deep_agent(
4    model="ollama:gemma4:e4b",
5)
6
7result = agent.invoke({"messages": [{"role": "user", "content": "How are you?"}]})
8
9print(result["messages"][-1].content)

 1{"model":"gemma4:e4b","stream":true,"options":{},
 2  "messages":[
 3    {"role":"system","content":"<系统提示词见下>"},
 4    {"role":"user","content":"How are you?"}],
 5    "tools":[
 6      {"type":"function","function":{"name":"write_todos","description":"Use this tool to create and manage a structured task list for your current work session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.\n\nOnly use this tool if you think it will be helpful in staying organized. If the user's request is trivial and takes less than 3 steps, it is better to NOT use this tool and just do the task directly.\n\n## When to Use This Tool\nUse this tool in these scenarios:\n\n1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions\n2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations\n3. User explicitly requests todo list - When the user directly asks you to use the todo list\n4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)\n5. The plan may need future revisions or updates based on results from the first few steps\n\n## How to Use This Tool\n1. When you start working on a task - Mark it as in_progress BEFORE beginning work.\n2. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation.\n3. You can also update future tasks, such as deleting them if they are no longer necessary, or adding new tasks that are necessary. Don't change previously completed tasks.\n4. You can make several updates to the todo list at once. For example, when you complete a task, you can mark the next task you need to start as in_progress.\n\n## When NOT to Use This Tool\nIt is important to skip using this tool when:\n1. There is only a single, straightforward task\n2. The task is trivial and tracking it provides no benefit\n3. The task can be completed in less than 3 trivial steps\n4. The task is purely conversational or informational\n\n## Task States and Management\n\n1. **Task States**: Use these states to track progress:\n   - pending: Task not yet started\n   - in_progress: Currently working on (you can have multiple tasks in_progress at a time if they are not related to each other and can be run in parallel)\n   - completed: Task finished successfully\n\n2. **Task Management**:\n   - Update task status in real-time as you work\n   - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)\n   - Complete current tasks before starting new ones\n   - Remove tasks that are no longer relevant from the list entirely\n   - IMPORTANT: When you write this todo list, you should mark your first task (or tasks) as in_progress immediately!.\n   - IMPORTANT: Unless all tasks are completed, you should always have at least one task in_progress to show the user that you are working on something.\n\n3. **Task Completion Requirements**:\n   - ONLY mark a task as completed when you have FULLY accomplished it\n   - If you encounter errors, blockers, or cannot finish, keep the task as in_progress\n   - When blocked, create a new task describing what needs to be resolved\n   - Never mark a task as completed if:\n     - There are unresolved issues or errors\n     - Work is partial or incomplete\n     - You encountered blockers that prevent completion\n     - You couldn't find necessary resources or dependencies\n     - Quality standards haven't been met\n\n4. **Task Breakdown**:\n   - Create specific, actionable items\n   - Break complex tasks into smaller, manageable steps\n   - Use clear, descriptive task names\n\nBeing proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully\nRemember: If you only need to make a few tool calls to complete a task, and it is clear what you need to do, it is better to just do the task directly and NOT call this tool at all.","parameters":{"type":"object","required":["todos"],"properties":{"todos":{"type":"array","items":{"description":"A single todo item with content and status.","properties":{"content":{"type":"string"},"status":{"enum":["pending","in_progress","completed"],"type":"string"}},"required":["content","status"],"type":"object"}}}}}},
 7      {"type":"function","function":{"name":"ls","description":"Lists all files in a directory.\n\nThis is useful for exploring the filesystem and finding the right file to read or edit.\nYou should almost ALWAYS use this tool before using the read_file or edit_file tools.",
 8        "parameters":{"type":"object","required":["path"],"properties":{"path":{"type":"string","description":"Absolute path to the directory to list. Must be absolute, not relative."}}}}},
 9      {"type":"function","function":{"name":"read_file","description":"Reads a file from the filesystem.\n\nAssume this tool is able to read all files. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.\n\nUsage:\n- By default, it reads up to 100 lines starting from the beginning of the file\n- **IMPORTANT for large files and codebase exploration**: Use pagination with offset and limit parameters to avoid context overflow\n  - First scan: read_file(path, limit=100) to see file structure\n  - Read more sections: read_file(path, offset=100, limit=200) for next 200 lines\n  - Only omit limit (read full file) when necessary for editing\n- Specify offset and limit: read_file(path, offset=0, limit=100) reads first 100 lines\n- Results are returned using cat -n format, with line numbers starting at 1\n- Lines longer than 5,000 characters will be split into multiple lines with continuation markers (e.g., 5.1, 5.2, etc.). When you specify a limit, these continuation lines count towards the limit.\n- You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful.\n- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.\n- Image files (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, etc.), audio and video files, and PDFs are returned as multimodal content blocks (see https://docs.langchain.com/oss/python/langchain/messages#multimodal).\n\nFor multimodal reads (image, audio, video, PDF, etc.):\n- Use `read_file(file_path=...)`\n- Do NOT use `offset`/`limit` for images (pagination is text-only)\n- If file details were compacted from history, call `read_file` again on the same path\n\n- You should ALWAYS make sure a file has been read before editing it.",
10        "parameters":{"type":"object","required":["file_path"],"properties":{"file_path":{"type":"string","description":"Absolute path to the file to read. Must be absolute, not relative."},"offset":{"type":"integer","description":"Line number to start reading from (0-indexed). Use for pagination of large files."},"limit":{"type":"integer","description":"Maximum number of lines to read. Use for pagination of large files."}}}}},
11      {"type":"function","function":{"name":"write_file","description":"Writes to a new file in the filesystem.\n\nUsage:\n- The write_file tool will create the a new file.\n- Prefer to edit existing files (with the edit_file tool) over creating new ones when possible.",
12        "parameters":{"type":"object","required":["file_path","content"],"properties":{"file_path":{"type":"string","description":"Absolute path where the file should be created. Must be absolute, not relative."},"content":{"type":"string","description":"The text content to write to the file. This parameter is required."}}}}},
13      {"type":"function","function":{"name":"edit_file","description":"Performs exact string replacements in files.\n\nUsage:\n- You must read the file before editing. This tool will error if you attempt an edit without reading the file first.\n- When editing, preserve the exact indentation (tabs/spaces) from the read output. Never include line number prefixes in old_string or new_string.\n- ALWAYS prefer editing existing files over creating new ones.\n- Only use emojis if the user explicitly requests it.",
14        "parameters":{"type":"object","required":["file_path","old_string","new_string"],"properties":{"file_path":{"type":"string","description":"Absolute path to the file to edit. Must be absolute, not relative."},"old_string":{"type":"string","description":"The exact text to find and replace. Must be unique in the file unless replace_all is True."},"new_string":{"type":"string","description":"The text to replace old_string with. Must be different from old_string."},"replace_all":{"type":"boolean","description":"If True, replace all occurrences of old_string. If False (default), old_string must be unique."}}}}},
15      {"type":"function","function":{"name":"glob","description":"Find files matching a glob pattern.\n\nSupports standard glob patterns: `*` (any characters), `**` (any directories), `?` (single character).\nReturns a list of absolute file paths that match the pattern.\n\nExamples:\n- `**/*.py` - Find all Python files\n- `*.txt` - Find all text files in root\n- `/subdir/**/*.md` - Find all markdown files under /subdir",
16        "parameters":{"type":"object","required":["pattern"],"properties":{"pattern":{"type":"string","description":"Glob pattern to match files (e.g., '**/*.py', '*.txt', '/subdir/**/*.md')."},"path":{"type":"string","description":"Base directory to search from. Defaults to root '/'."}}}}},
17      {"type":"function","function":{"name":"grep","description":"Search for a text pattern across files.\n\nSearches for literal text (not regex) and returns matching files or content based on output_mode.\nSpecial characters like parentheses, brackets, pipes, etc. are treated as literal characters, not regex operators.\n\nExamples:\n- Search all files: `grep(pattern=\"TODO\")`\n- Search Python files only: `grep(pattern=\"import\", glob=\"*.py\")`\n- Show matching lines: `grep(pattern=\"error\", output_mode=\"content\")`\n- Search for code with special chars: `grep(pattern=\"def __init__(self):\")`",
18        "parameters":{"type":"object","required":["pattern"],"properties":{"pattern":{"type":"string","description":"Text pattern to search for (literal string, not regex)."},"path":{"description":"Directory to search in. Defaults to current working directory."},"glob":{"description":"Glob pattern to filter which files to search (e.g., '*.py')."},"output_mode":{"type":"string","description":"Output format: 'files_with_matches' (file paths only, default), 'content' (matching lines with context), 'count' (match counts per file).","enum":["files_with_matches","content","count"]}}}}},
19      {"type":"function","function":{"name":"task","description":"Launch an ephemeral subagent to handle complex, multi-step independent tasks with isolated context windows.\n\nAvailable agent types and the tools they have access to:\n- general-purpose: General-purpose agent for researching complex questions, searching for files and content, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you. This agent has access to all tools as the main agent.\n\nWhen using the Task tool, you must specify a subagent_type parameter to select which agent type to use.\n\n## Usage notes:\n1. Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses\n2. When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.\n3. Each agent invocation is stateless. You will not be able to send additional messages to the agent, nor will the agent be able to communicate with you outside of its final report. Therefore, your prompt should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final and only message to you.\n4. The agent's outputs should generally be trusted\n5. Clearly tell the agent whether you expect it to create content, perform analysis, or just do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent\n6. If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.\n7. When only the general-purpose agent is provided, you should use it for all tasks. It is great for isolating context and token usage, and completing specific, complex tasks, as it has all the same capabilities as the main agent.\n\n### Example usage of the general-purpose agent:\n\n<example_agent_descriptions>\n\"general-purpose\": use this agent for general purpose tasks, it has access to all tools as the main agent.\n</example_agent_descriptions>\n\n<example>\nUser: \"I want to conduct research on the accomplishments of Lebron James, Michael Jordan, and Kobe Bryant, and then compare them.\"\nAssistant: *Uses the task tool in parallel to conduct isolated research on each of the three players*\nAssistant: *Synthesizes the results of the three isolated research tasks and responds to the User*\n<commentary>\nResearch is a complex, multi-step task in it of itself.\nThe research of each individual player is not dependent on the research of the other players.\nThe assistant uses the task tool to break down the complex objective into three isolated tasks.\nEach research task only needs to worry about context and tokens about one player, then returns synthesized information about each player as the Tool Result.\nThis means each research task can dive deep and spend tokens and context deeply researching each player, but the final result is synthesized information, and saves us tokens in the long run when comparing the players to each other.\n</commentary>\n</example>\n\n<example>\nUser: \"Analyze a single large code repository for security vulnerabilities and generate a report.\"\nAssistant: *Launches a single `task` subagent for the repository analysis*\nAssistant: *Receives report and integrates results into final summary*\n<commentary>\nSubagent is used to isolate a large, context-heavy task, even though there is only one. This prevents the main thread from being overloaded with details.\nIf the user then asks followup questions, we have a concise report to reference instead of the entire history of analysis and tool calls, which is good and saves us time and money.\n</commentary>\n</example>\n\n<example>\nUser: \"Schedule two meetings for me and prepare agendas for each.\"\nAssistant: *Calls the task tool in parallel to launch two `task` subagents (one per meeting) to prepare agendas*\nAssistant: *Returns final schedules and agendas*\n<commentary>\nTasks are simple individually, but subagents help silo agenda preparation.\nEach subagent only needs to worry about the agenda for one meeting.\n</commentary>\n</example>\n\n<example>\nUser: \"I want to order a pizza from Dominos, order a burger from McDonald's, and order a salad from Subway.\"\nAssistant: *Calls tools directly in parallel to order a pizza from Dominos, a burger from McDonald's, and a salad from Subway*\n<commentary>\nThe assistant did not use the task tool because the objective is super simple and clear and only requires a few trivial tool calls.\nIt is better to just complete the task directly and NOT use the `task` tool.\n</commentary>\n</example>\n\n### Example usage with custom agents:\n\n<example_agent_descriptions>\n\"content-reviewer\": use this agent after you are done creating significant content or documents\n\"greeting-responder\": use this agent when to respond to user greetings with a friendly joke\n\"research-analyst\": use this agent to conduct thorough research on complex topics\n</example_agent_descriptions>\n\n<example>\nuser: \"Please write a function that checks if a number is prime\"\nassistant: Sure let me write a function that checks if a number is prime\nassistant: First let me use the Write tool to write a function that checks if a number is prime\nassistant: I'm going to use the Write tool to write the following code:\n<code>\nfunction isPrime(n) {\n  if (n <= 1) return false\n  for (let i = 2; i * i <= n; i++) {\n    if (n % i === 0) return false\n  }\n  return true\n}\n</code>\n<commentary>\nSince significant content was created and the task was completed, now use the content-reviewer agent to review the work\n</commentary>\nassistant: Now let me use the content-reviewer agent to review the code\nassistant: Uses the Task tool to launch with the content-reviewer agent\n</example>\n\n<example>\nuser: \"Can you help me research the environmental impact of different renewable energy sources and create a comprehensive report?\"\n<commentary>\nThis is a complex research task that would benefit from using the research-analyst agent to conduct thorough analysis\n</commentary>\nassistant: I'll help you research the environmental impact of renewable energy sources. Let me use the research-analyst agent to conduct comprehensive research on this topic.\nassistant: Uses the Task tool to launch with the research-analyst agent, providing detailed instructions about what research to conduct and what format the report should take\n</example>\n\n<example>\nuser: \"Hello\"\n<commentary>\nSince the user is greeting, use the greeting-responder agent to respond with a friendly joke\n</commentary>\nassistant: \"I'm going to use the Task tool to launch with the greeting-responder agent\"\n</example>",
20        "parameters":{"type":"object","required":["description","subagent_type"],"properties":{"description":{"type":"string","description":"A detailed description of the task for the subagent to perform autonomously. Include all necessary context and specify the expected output format."},
21        "subagent_type":{"type":"string","description":"The type of subagent to use. Must be one of the available agent types listed in the tool description."}}}}}
22    ]
23}

 1create_deep_agent(
 2    model: str | BaseChatModel | None = None,
 3    tools: Sequence[BaseTool | Callable | dict[str, Any]] | None = None,
 4    *,
 5    system_prompt: str | SystemMessage | None = None,
 6    middleware: Sequence[AgentMiddleware] = (),
 7    subagents: Sequence[SubAgent | CompiledSubAgent | AsyncSubAgent] | None = None,
 8    skills: list[str] | None = None,
 9    memory: list[str] | None = None,
10    permissions: list[FilesystemPermission] | None = None,
11    backend: BackendProtocol | BackendFactory | None = None,
12    interrupt_on: dict[str, bool | InterruptOnConfig] | None = None,
13    response_format: ResponseFormat[ResponseT] | type[ResponseT] | dict[str, Any] | None = None,
14    context_schema: type[ContextT] | None = None,
15    checkpointer: Checkpointer | None = None,
16    store: BaseStore | None = None,
17    debug: bool = False,
18    name: str | None = None,
19    cache: BaseCache | None = None
20) -> CompiledStateGraph[AgentState[ResponseT], ContextT, _InputAgentState, _OutputAgentState[ResponseT]]

1from deepagents import create_deep_agent
2from langchain_quickjs import CodeInterpreterMiddleware
3
4agent = create_deep_agent(
5    model="ollama:gemma4:e4b",
6    middleware=[CodeInterpreterMiddleware()],
7)

 1python_agent = {
 2  "name": "python_agent",
 3  "model": "ollama:llama3.2:1b",
 4  "description": "A helpful assistant to help writing python code.",
 5  "system_prompt": "You are a good python coding helper.",
 6}
 7
 8agent = create_deep_agent(
 9  # model="ollama:gemma4:e4b",
10  model="bedrock:us.anthropic.claude-haiku-4-5-20251001-v1:0",
11  system_prompt=(
12    "You are a dispatcher agent. Analyze the user's question and route it "
13    "to the most appropriate subagent. For Python coding questions, "
14    "delegate to the python_agent."
15  ),
16  subagents=[python_agent]
17  ,)
18
19result = agent.invoke({"messages": [{"role": "user", "content": "write python hello world code"}]})

 1---
 2name: roll-dice,
 3description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.),
 4  roll dice, or generate a random dice roll.
 5---
 6
 7To roll a die, use the following command that generates a random number from 1
 8to the given number of sides:
 9
10```bash
11echo $((RANDOM % <sides> + 1))
12```
13
14```powershell
15Get-Random -Minimum 1 -Maximum (<sides> + 1)
16```
17
18Replace `<sides>` with the number of sides on the die (e.g., 6 for a standard die, 20 for a d20).

 1import subprocess
 2
 3from deepagents import create_deep_agent
 4
 5def bash_exec(command: str) -> str:
 6    """Execute a shell command and return its output."""
 7    print(f"Executed command: {command}")
 8    result = subprocess.run(command, shell=True, capture_output=True, text=True)
 9    return result.stdout.strip() or result.stderr.strip()
10
11
12agent = create_deep_agent(
13    model="ollama:gemma4:e4b",
14    skills=["/Users/yanbin/Workspaces/study/langchain-study/skills"],
15    tools=[bash_exec],
16)
17
18result = agent.invoke({"messages": [{"role": "user", "content": "roll a dice between 1 to 20"}]})
19
20for message in result["messages"]:
21    message.pretty_print()

 1Executed command: echo $(( RANDOM % 20 + 1 ))
 2================================ Human Message =================================
 3
 4roll a dice between 1 to 20
 5================================== Ai Message ==================================
 6Tool Calls:
 7  bash_exec (b6a0cf10-38af-4fd4-906c-cae998fa3d8c)
 8 Call ID: b6a0cf10-38af-4fd4-906c-cae998fa3d8c
 9  Args:
10    command: echo $(( RANDOM % 20 + 1 ))
11================================= Tool Message =================================
12Name: bash_exec
13
1410
15================================== Ai Message ==================================
16
1710

 1from deepagents import create_deep_agent
 2from deepagents.backends import FilesystemBackend
 3
 4agent = create_deep_agent(
 5    model="ollama:gemma4:e4b",
 6    backend=FilesystemBackend(root_dir="/Users/yanbin/Workspaces/study/langchain-study", virtual_mode=False),
 7    memory=[
 8        "./AGENTS.md"
 9    ],
10)
11
12result = agent.invoke({"messages": [{"role": "user", "content": "please say my name"}]})
13
14for message in result["messages"]:
15  message.pretty_print()

1My name is Yanbin

1================================ Human Message =================================
2
3please say my name
4================================== Ai Message ==================================
5
6Your name is Yanbin.

1<agent_memory>\n./AGENTS.md\nMy name is Yanbin\n</agent_memory>

1class HarnessProfile:
2  base_system_prompt: str | None = None
3  system_prompt_suffix: str | None = None
4  tool_description_overrides: Mapping[str, str] = field(default_factory=dict)
5  excluded_tools: frozenset[str] = frozenset()
6  excluded_middleware: frozenset[type[AgentMiddleware] | str] = frozenset()
7  extra_middleware: Sequence[AgentMiddleware] | Callable[[], Sequence[AgentMiddleware]] = ()
8  general_purpose_subagent: GeneralPurposeSubagentProfile | None = None

1from deepagents import HarnessProfile, register_harness_profile
2
3# Append a system-prompt suffix whenever gpt-5.4 is selected.
4register_harness_profile(
5    "ollama:gemma4:e4b",
6    HarnessProfile(system_prompt_suffix="Respond in under 100 words."),
7)