配置你的智能体#

从 create_agent(model) 开始。在创建客户端时配置整个对话共享的行为；在调用 run 或 stream 时，只覆盖单个请求需要变化的部分。

本页假设你已经按连接模型提供商配置好 model。下面的示例都应该写在异步函数内部。

一次性选定默认值#

from zett_agent.agent import AgentRunConfig
from zett_agent.client import create_agent
from zett_agent.model import ReasoningEffort

client = await create_agent(
    model,
    config=AgentRunConfig(session_id="review-42"),
    system_prompt="Review changes carefully. Explain risks before suggesting edits.",
    reasoning_effort=ReasoningEffort.MEDIUM,
    parallel_tool_call=True,
    max_iterations=12,
    max_internal_messages=4,
)
reply = await client.run("Review this function.")

create_agent 返回一个初始化好的 AgentClient。需要外部输入之类的高级运行时操作时，请使用 client.agent。客户端和直接使用 Agent 的 API 共用同一个循环；客户端还会额外把事件分发给已绑定的回调。

设置项及其作用范围#
设置项	默认值	作用
`system_prompt`	有帮助的助手	每个请求都会重建的应用指令。
`tools`	空	模型可以请求的具名操作。参见定义并注册工具。
`extensions`	`None`	保留默认的历史记录和工具 guidelines，或者用一个显式列表替换它们。
`reasoning_effort`	`MEDIUM`	一个与模型提供商无关的偏好；是否支持取决于端点和模型。
`parallel_tool_call`	`True`	允许对本地并行工具发起并发调用，并在提供商支持时请求该支持。
`max_iterations`	`36`	每次用户输入或内部输入允许的最大模型调用次数，包括工具结果之后的调用。
`max_internal_messages`	`8`	限制一次请求期间排队的 internal continuation。
`event_dispatcher`	`None`	可选的回调，在客户端消费事件时被等待执行。

请为 max_iterations 使用正整数，为 max_internal_messages 使用非负整数（0 表示禁止 internal continuation）。超出上限会抛出 AgentIterationLimitError，而不会返回一份成功的部分答案。这两个上限都不限制费用、token 数、墙钟时间或单个响应中的工具数量。请另外设置应用超时和工具限额；参见集成到应用。

覆盖单个请求#

reply = await client.run(
    "Analyze the difficult edge cases.",
    reasoning_effort=ReasoningEffort.HIGH,
    parallel_tool_call=False,
    metadata={"source": "review-form", "trace_id": "trace-7"},
    tags={"task": "code-review"},
)

这些值只对本次调用生效。你也可以传入 model=other_model，为单个请求换用另一个模型适配器；或者用 model=None 创建客户端，在每次调用时提供模型。这两个适配器仍然由你的应用负责。更换模型并不会让特定于提供商的推理状态变得可移植；参见连接模型提供商。

stream 接受同样的选项。compact 接受 identity、model、metadata 和 tags，但不会启动普通的用户请求。

标识与行为相互独立#

reply = await client.run(
    "Continue the review.",
    config=AgentRunConfig(session_id="review-42", request_id="request-7"),
)

复用 session_id 即可指向同一个对话。省略 config 会使用创建客户端时选定的会话；如果你从未指定过，运行时会生成一个 UUIDv7 ID，可以在事件流中通过 event.session_id 读取。如果应用需要存储并重新打开这个 ID，请显式选定它。

request_id 是应用层的关联 ID，而不是幂等键。同一个 ID 发送两次不会对工作或工具副作用去重。parent_session_id 标识被委派的对话，而 cache_key 只是提供商缓存路由的提示，既不是历史记录存储，也不是租户隔离。关于持久对话，参见保存并恢复对话。

metadata 并不是提示词#

请求的 metadata 和 tags 必须包含与 JSON 兼容的数据。它们通过 context.metadata 和 context.tags 传到扩展，并记录在持久化消息旁边。内置的模型提供商不会把它们发送给模型。

要让模型看到某些信息，请把它写进用户消息，或者通过扩展添加明确的指令。不要以为把账号、语言或权限放进 metadata 就能改变模型的行为。真正的约束应该放在你的应用或工具中间件里。

谨慎组合扩展#

extensions=None 会启用 InMemoryMessageAccumulator 和 ToolGuidelinesExtension。任何显式序列都会替换这两个默认项，包括 extensions=[]。

进程内历史记录

from zett_agent.extensions.agents_md import AgentsMdExtension
from zett_agent.extensions.memory import InMemoryMessageAccumulator
from zett_agent.extensions.tool_guidelines import ToolGuidelinesExtension

client = await create_agent(
    model,
    extensions=[
        InMemoryMessageAccumulator(),
        ToolGuidelinesExtension(),
        AgentsMdExtension(directory="workspace", include_parents=False),
    ],
)

持久化历史记录

from zett_agent.extensions.sqlite import SQLiteSessionExtension
from zett_agent.extensions.tool_guidelines import ToolGuidelinesExtension

history = SQLiteSessionExtension("sessions.sqlite")
try:
    client = await create_agent(
        model,
        extensions=[history, ToolGuidelinesExtension()],
    )
    reply = await client.run("Remember this conversation.")
finally:
    await history.close()

请只使用一个可恢复历史记录的扩展，不要同时使用内存和 SQLite。扩展实例可能持有状态：复用同一个实例会有意共享该状态，而新建一个内存累加器不会恢复旧的对话。内置扩展按优先级运行，数值小的先运行，优先级相同时按列表顺序。通常你不需要调整优先级；自定义扩展可以参考生命周期钩子参考。

下一步：要把这套配置集成到服务中，请看集成到应用；需要针对项目的指引，请看加载项目指令。