Chapter 01 · Your first deep agent and its file tools

Chapters that use a model need a tool-calling model service and API key (any OpenAI-compatible endpoint); running incurs cost.

Mechanics and design choices

A deep agent is more than a model call: it ships with a virtual filesystem (ls/read_file/write_file/edit_file/delete/glob/grep) and a default general-purpose subagent. The default backend is StateBackend, so files live in thread state, never on your disk. Give the model a simple domain tool and ask it to write the result to a file to observe the tool-plus-filesystem loop.

Example

import os
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from deepagents import create_deep_agent

@tool
def course_hours(course: str) -> str:
    """Return estimated study hours for a known course."""
    return {"langgraph": "12", "deepagents": "10"}.get(course.lower(), "unknown")

model = ChatOpenAI(
    model=os.environ["MODEL_ID"],
    api_key=os.environ["DEEPAGENT_API_KEY"],
    base_url=os.environ.get("DEEPAGENT_BASE_URL", "https://api.openai.com/v1"),
)

agent = create_deep_agent(
    model=model,
    tools=[course_hours],
    system_prompt="You are a course planning assistant. Record results with the write_file tool.",
)

config = {"configurable": {"thread_id": "ch01"}}
result = agent.invoke(
    {"messages": [{"role": "user", "content": "Use course_hours for deepagents, then write the answer to /plan.txt."}]},
    config=config,
)
print(result["messages"][-1].content)

import pathlib
assert not pathlib.Path("/plan.txt").exists()  # file lives in thread state, not on disk
print("ok: no /plan.txt on the host filesystem")

Run and verify

Also install langchain-openai. Configure MODEL_ID and DEEPAGENT_API_KEY (optionally DEEPAGENT_BASE_URL). Acceptance: the final message mentions 10 hours and /plan.txt does not exist on your filesystem because it belongs to the StateBackend.

Pitfalls

Do not assume files land on disk: the default backend is thread-local virtual state. Use StoreBackend for cross-thread durability and FilesystemBackend for real project files. Tools are capabilities visible to the model, not a security boundary: your code still validates arguments and authorization.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What is the default backend?

2. Does write_file need installation?

3. Are files shared across threads by default?

4. Do tools replace authorization checks?

Hands-on exercises

1. Read /plan.txt back with ls and read_file.
2. Use an unknown course name and verify the unknown branch.
3. List the available filesystem tools and their purposes.

Official references

• overview
• backends

Verified on 2026-09-17 with Deep Agents 0.7.15.