Agent 与工具调用 · 知识点
Agent 不是「包了一层 SDK」。它是：模型看当前上下文，决定调什么工具、读什么观察、何时停止。没有循环和停止条件，只是单轮补全或一次 Function Calling。
框架对比和 SDK API 看 应用框架；平台（Coze / Dify）看 平台与业务。本页只讲机制和取舍。
0. 总图
一次 Agent 步进大致是：
text
目标 + 系统约束
→ 装配上下文（指令 / 历史 / 状态 / 上次观察）
→ 模型看见工具 schema（不是函数体）
→ 决定：回答 | 调工具 | 问人 | 停止
→ 服务端执行工具（权限、超时、校验）
→ 观察写回窗口
→ 再想，直到停止条件五块必须同时在：
- LLM 适配 — 聊天、流式、tool calling 统一。换模型不能改业务。
- 工具 — 名字、说明、参数 schema、执行。模型只点名 + 填表。
- 上下文 — 系统提示、历史、工具返回怎么进窗口，爆了要裁。
- 控制流 — Chain / Loop / DAG：下一步谁说了算、怎么停。
- 停止与权限 — 步数上限、重复动作打断、写操作审批。少一块就只是脚本套模型。
口条：大脑可换、双手可插、记忆可裁、中枢能停。
重点 1. 何时上 Agent
不要为所有任务构建 Agent。
| 先问 | 偏工作流 | 偏 Agent |
|---|---|---|
| 决策树能不能画清 | 能 → 写死节点 | 模糊、要看观察再选 |
| 错误成本 | 高 → 限制权限或人工 | 可重试、可降级 |
| 价值 | 低价值别烧 token | 复杂、高价值才配循环 |
| 关键子能力 | 核心步骤都不会 → 先验证 | 代码生成、检索、调试等已能单独做对 |
保持简洁：环境（它能看见什么）、工具集、系统提示。初期不要先上多 Agent、长期记忆和复杂规划。优化成本和延迟，放在基础行为稳定之后。
像 Agent 一样思考：它只能基于当前被装入的有限窗口做决策。预算取决于窗口、系统提示、历史、工具返回、成本和延迟，不是固定的 10–20k token。看轨迹日志，不要只看最终答案。
能规则化的别上 Agent。Batch 打分、发票审核若规则清晰，走脚本；非结构化 + 模糊规则才考虑循环，并且要卡单条预算。
重点 2. 模型怎么看见工具；FC vs MCP
模型看不见函数体，只看见 JSON Schema（名字、干什么、参数）。框架把函数编成 schema 塞进 tools；模型回 tool call，运行时在服务端执行。说明写糊了就会乱填参数；执行失败是框架的事。
Function Calling 和 MCP 不是二选一：
| 维度 | Function Calling | MCP |
|---|---|---|
| 定位 | 模型厂商私有插头（OpenAI、Qwen） | 开放协议，工具怎么对外暴露 |
| 扩展性 | 每个模型单独适配描述和解析 | Server 写一次，多 Client 能连 |
| 复杂度 | 简单、单次调用更省 | 发现、多轮、跨应用复用 |
| 安全 | 常绑云端 Key | 可本地部署，鉴权仍在服务端 |
模型侧往往还是 FC / tool call，连上的可以是 MCP Server。简单原子任务直接 FC 更省事。项目里文档检索走 MCP、和网页共用一套检索时，鉴权仍在服务端，不靠桌面 TXT 示例。
MCP 三角：Host（跑模型的环境）→ Client（Host 里发起请求）→ Server（暴露 Resources / Tools / Prompts）。具体能力和安全策略取决于实现。参考：https://modelcontextprotocol.io/introduction（核验于 2026-09-12）。
重点 3. Chain / Loop / DAG
控制流差在「下一步谁决定、有没有环」。
| 形态 | 下一步谁定 | 典型 | 别用在 |
|---|---|---|---|
| Chain | 人写死 | 线性 RAG、格式化 | 要试错、要看观察再选 |
| Loop（ReAct） | 模型：想 → 调工具 → 观察 → 再想 | 检索不够再搜、修代码 | 没有步数上限 |
| DAG | 人写死依赖、无环 | 接力任务、固定审批 | 要循环重试就升级到带环的图 |
有环、要状态、要人审 → LangGraph 一类图，见 LangGraph。口条：流水线走链，试错走环，接力走 DAG。
写一个 Agent 框架要同时解决：LLM 适配、工具注册与调度、Context 裁剪、控制流编排。少一块就只是脚本。
重点 4. 死循环、权限、降级
死循环
- 检测：连续多次 Action 语义极像且没有新 Observation → 强制打断。
- 系统提示：换策略或问用户；必须有全局步数上限。
- ReAct 典型坏法：反复同一工具、不给 Final Answer。
权限
- 工具权限由服务端身份、租户和策略执行。模型只能提出调用意图，不能自行获得权限。
- 写操作、外发、删除、高成本：参数校验、额度、超时、幂等键、人工确认。
- Prompt / 检索文档当数据，不能改系统指令。
失败降级
- 工具超时、schema 校验失败、无证据：重试、安全提示、转人工或只给来源。
- 轨迹评测同时看结果与过程：是否调用了允许的工具、是否遵守步骤上限、失败时是否安全退出。
5. 进阶
速度 vs 深度
双层：简单查询直接调 API 或短链；复杂再 Planner 拆任务。前面加路由，意图简单就短路。能 Workflow 写死的别上自主循环。
沙箱
模型生成的代码可能删盘、死循环，不能在宿主机裸跑。隔离环境只回传 stdout/stderr，超时或内存超限就销毁。没落地就说「原则 + 自己项目还没有代码执行」，不要虚构。
单 Agent vs 多 Agent
- 单：工具少、步骤短、上下文单一。
- 多：窗口太长会忘需求、角色指令冲突（规划 / 写码 / 测试拆开）。先拆上下文和职责，再拆进程。
自我修复：报错 + 旧代码回灌，要求分析并重写；max_retries（如 3），超限抛给用户。工具要尽量原子、可幂等。
反应式 / 深思熟虑 / 混合
| 类型 | 做法 | 适合 | 风险 |
|---|---|---|---|
| 反应式 | 当前观察立刻动作 | 规则明确、要快 | 短视、易绕圈 |
| 深思熟虑 | 先建模再规划 | 多步、要长期目标 | 慢、计划过期 |
| 混合 | 紧急走反应，常规走规划 | 自动驾驶一类 | 仲裁本身要简单 |
示例代码见文末 12–14，不要背成自己的上线经历。
6. 了解
FastMCP — Python 侧常用的 MCP Server 框架：@mcp.tool() 注册，stdio / HTTP 传输。用前按当前版本看官方文档。
结构化输出 — 软提示会漏括号。官方 Structured Output 能用就用官方。跨引擎硬约束可用 Outlines（解码时屏蔽非法 token）。四种约束：JSON Schema、正则、多选、嵌套 Pydantic。分类用多选；一个字段用正则；扁平对象用 schema；业务单据用嵌套。
关闭 Qwen3 思考 — 硬开关（请求 enable_thinking: false 或服务启动默认）比 Prompt 里写「不要思考」稳。/no_think 是软开关。JSON / 工具调用、低延迟 API 优先硬关。
7. 建议复习顺序
- Agent ≠ 单轮调用 ≠ 一次 FC
- 模型只看见 schema；执行和权限在服务端
- FC vs MCP：插头 vs 插槽
- Chain / Loop / DAG，以及何时不上 Agent
- 死循环、步数上限、写操作审批
- 沙箱、路由、单/多 Agent
- 框架和平台：04 / 05，不要和机制混背