各部分如何配合

一个循环，几条有用的边界

智能体在模型调用和工具执行之间交替，直到得出最终答案。模型提供商、工具和扩展为这个循环提供各种能力。你的应用可以单独采用它们，而不必同时采用一套 Web 服务器、UI 或另一个应用的数据模型。

your application / UI
       │
       ▼
  AgentClient ─────────▶ AgentEventDispatcher ──▶ your callbacks
       │
       ▼
     Agent ◀───────────▶ AgentModel ──────────▶ provider SDK
       │
       ├── AgentTool ───────▶ your typed function
       └── AgentExtension ──▶ context, sessions, approvals, compaction

谁拥有什么

对象	职责
Agent	接收请求，运行模型/工具循环，并负责清理。
AgentClient	提供便捷的创建方式和事件处理；把运行时暴露为 client.agent。
AgentModel	与某一个模型提供商通信，并把它的流式输出规范化。
AgentRunContext	与扩展共享的请求级状态；请使用它，而不是全局状态。
AgentExtension	在文档列出的钩子上提供可选行为；默认什么都不做。
AgentEventDispatcher	你在某条流上的回调；它从不注入上下文，也不运行工具。

是组合，不是第二个运行时

create_agent 只是包装了一个 Agent，并不会创建另一套循环。你可以直接对Agent使用 async for，把已有的 Agent 包装进客户端，并通过扩展添加行为，而无需继承 Agent。

你的应用拥有自己传入的资源。运行时只关闭自己打开的流，但绝不会关闭你提供的模型提供商或数据库——这些资源要在应用关闭时由你自己释放。

该用哪条边界？

• 用模型适配器连接端点，而不是用它管理对话历史。

• 对模型可能请求的操作要用工具，而不是再套一层模型循环。

• 用扩展处理上下文、权限、持久化，或请求过程中的行为。

• 用分发器处理只观察 UI 事件的呈现和遥测。

例如，一个代码评审助手可以组合模型提供商、只读工具、项目指令和会话存储。它的 UI 只需展示产生的事件，不必知道这些能力是如何实现的。组合方式见配置你的智能体；内置扩展不覆盖你的工作流时，请见编写你的第一个扩展。

限制与安全

• max_iterations 限制每条用户输入或内部输入能触发的模型调用次数。工具往返会消耗这个额度。

• max_internal_messages 限制一次请求中排队的 internal continuation 数量。

• 这两个限制都不是花费上限，也不是权限边界。

文件系统、shell 和 MCP 工具以你的进程或服务器的权限运行。工具 guidelines 只是说明，不是强制约束。请用显式的允许列表、审批规则、资源限制和进程隔离来防护不可信的输入。

下一步：看请求生命周期，了解一次请求内部钩子的确切顺序。