03 Custom state schema：可变图状态

它是什么

Custom state schema 是 Deep Agent 的可变图状态扩展，适合保存运行中会变化并需要 checkpoint 的数据。它解决的问题是：工具和 middleware 要共享“当前页面、已收集文件、计数器”等运行中状态。不可变的用户配置仍然优先放 runtime context。

最小代码

文件：deepagent_src/context_engineering_teach/03_custom_state_schema.py

class ResearchState(DeepAgentState):
    page_url: str
    file_urls: list[str]


@tool
def cite_page(runtime: ToolRuntime) -> str:
    """Return the page URL stored in mutable agent state."""
    return runtime.state["page_url"]

运行

uv run python deepagent_src/context_engineering_teach/03_custom_state_schema.py

预期输出：

custom state schema real agent ok

验证方式

脚本确认 ResearchState 暴露了新增 state 字段，并真实调用 Agent，要求 Agent 调用 cite_page 工具从 runtime.state 读到 page_url。

常见误区

别用 state 存 API key、用户角色这类每轮静态配置。那些信息放 runtime context 更清楚，也更不容易被模型上下文污染。

相关资源

查看示例代码：deepagent_src/context_engineering_teach/03_custom_state_schema.py

from __future__ import annotations

from typing import get_type_hints

from deepagents import DeepAgentState, create_deep_agent
from langchain.tools import ToolRuntime, tool

from _model import get_real_model
from deepagent_src.agent_output import invoke_and_pretty_print


class ResearchState(DeepAgentState):
    page_url: str
    file_urls: list[str]


@tool
def cite_page(runtime: ToolRuntime) -> str:
    """Return the page URL stored in mutable agent state."""
    return runtime.state["page_url"]


def main() -> None:
    agent = create_deep_agent(
        model=get_real_model(),
        tools=[cite_page],
        state_schema=ResearchState,
    )

    result = invoke_and_pretty_print(
        agent,
        {
            "messages": [
                {
                    "role": "user",
                    "content": (
                        "必须调用 cite_page 工具读取当前页面 URL，"
                        "然后只输出这个 URL。"
                    ),
                }
            ],
            "page_url": "https://example.com/report",
            "file_urls": [],
        }
    )

    state_hints = get_type_hints(ResearchState)
    tool_outputs = [
        getattr(message, "content", "")
        for message in result["messages"]
        if message.__class__.__name__ == "ToolMessage"
    ]

    assert state_hints["page_url"] is str
    assert state_hints["file_urls"] == list[str]
    assert any("https://example.com/report" in output for output in tool_outputs)
    print("custom state schema real agent ok")


if __name__ == "__main__":
    main()