AI Agent on Weiuou的博客

AI Agent 开发

Sun, 05 Jul 2026 18:00:00 +0800

AI Agent 开发不是把 LLM 接上几个工具就结束了，而是围绕模型建立一套可执行、可观察、可恢复、可评测的工程系统。

一句话定义

AI Agent 是一个能根据目标选择动作、调用工具、读取反馈并继续决策的系统；Agent 开发的重点，是把这个循环约束在可靠的工程边界里。

核心概念表

概念	作用	相关问题
Agent Loop	让模型在生成、工具调用、观察之间循环	什么时候停止，工具错误怎么返回
Tool / Function Calling	把模型意图转换为受控的外部能力	schema、参数校验、tool choice
Agent Harness	包装 loop 的工程运行时	trace、replay、错误恢复、安全边界
Tracing	记录一次 Agent run 的执行过程	哪一步失败，为什么失败
Eval Harness	用固定任务集评估改动效果	改 prompt、tool schema 后有没有变好
Guardrail	在高风险动作前后做约束	权限、注入、敏感信息、输出处理

学习路径

先理解最小 Agent Loop，再给它补上工具结果格式、trace、错误恢复和上下文管理。等系统可以稳定复盘后，再引入 eval，用固定任务判断改动是否真的提升了行为。

对于真实应用，安全边界要尽早进入设计。模型可以提出动作意图，但系统必须决定它是否真的有权执行。

MCP 学习路线

Sun, 05 Jul 2026 18:00:00 +0800

MCP 的价值在于把 AI 应用和外部系统之间的连接方式标准化。理解 MCP 时，不要只看“它能调用工具”，还要看 Host、Client、Server 如何分工。

一句话定义

MCP 是一种让 AI 应用连接外部工具、数据源和提示模板的开放协议，可以把它理解为 AI 应用访问外部上下文的标准接口。

核心概念表

概念	作用	常见例子
MCP Host	使用 MCP 能力的 AI 应用	Codex、Claude Desktop
MCP Client	Host 内部负责连接某个 Server 的组件	每个 Server 通常对应一个 Client
MCP Server	向 AI 应用暴露能力的程序	文件系统、GitHub、数据库、浏览器
Tools	主动执行动作的接口	搜索、写入、调用 API
Resources	只读上下文或数据源	文件、文档、数据库记录
Prompts	可复用的任务模板	代码审查模板、调研模板

学习路径

先弄清楚 MCP 解决的是“连接标准化”问题，再理解 C-S 架构里的 Host、Client、Server。之后再看 Server 暴露的三类能力：Tools、Resources、Prompts。

如果你已经在做 Agent 应用，可以把 MCP 放到工具生态和上下文管理里理解：它不是替代 Agent Harness，而是给 Harness 提供更标准的能力入口。

Function Calling

Mon, 29 Jun 2026 23:59:00 +0800

本文结论

Function calling 的本质是让模型输出受 schema 约束的工具调用意图，再由程序决定是否执行。
工具描述、参数 schema、tool choice 和工具数量，会直接影响模型选择工具和生成参数的稳定性。
严格模式适合默认开启，但需要遵守 additionalProperties: false、字段 required 和可空类型等约束。
Streaming 不只适合展示文本进度，也可以实时观察函数参数是如何逐步生成的。

适合谁读

正在给 LLM 应用接入外部工具、数据库或业务 API 的开发者。
想理解 tool schema、tool choice、并行调用和严格模式如何影响 Agent 行为的人。
准备把 Function calling 放进 Agent Harness 或 MCP 工具体系里的人。

什么是 Function calling

Function calling 是一种强大且灵活的方式，让 LLM 能够与外部系统进行交互，获取模型训练数据之外的大量信息。

如果 AI 应用程序包含复杂的功能或数据库结构，可以将函数调用与工具搜索功能结合，来按需加载工具，不过只有少部分新模型支持 tool_search。

Function calling 定义与主要参数

function 的定义就比较简单，也是使用 JSON Schema，例子如下：

{
  "type": "function",
  "name": "get_weather",
  "description": "Retrieves current weather for the given location.",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City and country e.g. Bogotá, Colombia"
      },
      "units": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Units the temperature will be returned in."
      }
    },
    "required": ["location", "units"],
    "additionalProperties": false
  },
  "strict": true
}

其中主要的参数和作用如下：

Field	Description
`type`	`function`
`name`	函数的名称（例如：`get_weather`）
`description`	关于该功能的使用时间与方式的详细说明
`parameters`	用于定义该函数输入参数的 JSON 模式
`strict`	是否对函数调用启用严格模式

然后比较有意思的是 namespaces 的概念，类似于编程语言中的命名空间，有助于帮助 AI 整理和选择各种类似的工具。

{
  "type": "namespace",
  "name": "crm",
  "description": "CRM tools for customer lookup and order management.",
  "tools": [
    {
      "type": "function",
      "name": "get_customer_profile",
      "description": "Fetch a customer profile by customer ID.",
      "parameters": {
        "type": "object",
        "properties": {
          "customer_id": {
            "type": "string"
          }
        },
        "required": ["customer_id"],
        "additionalProperties": false
      }
    },
    {
      "type": "function",
      "name": "list_open_orders",
      "description": "List open orders for a customer ID.",
      "defer_loading": true,
      "parameters": {
        "type": "object",
        "properties": {
          "customer_id": {
            "type": "string"
          }
        },
        "required": ["customer_id"],
        "additionalProperties": false
      }
    }
  ]
}

例如上面这个用于 CRM 系统的搜索工具，还可以定义其他的比如 OA 系统的 xx 工具。一旦你希望你的 AI 应用于庞大的工具生态，可以使用前面提到的 tool_search 来延迟加载部分或全部工具。

最佳实践

编写详细、清晰的函数名称、参数说明以及使用说明。
- 明确说明函数用途，参数的用途以及格式，输出的结果代表什么含义。
- 利用 system prompt 来说明什么时候应该/不该使用某功能。
- 举例说明常见的情况和边缘情况，尤其是容易反复出现错误的情况。
- 对于延迟加载的工具，应在函数描述中提供详细的操作指南同时保持命名空间简洁，这分别有助于 LLM 正确使用已加载工具和正确决定应该加载哪个工具。
遵循软件工程的最佳实践。
- 让工具直观易用。
- 用枚举和对象结构来确保无效状态无法被表达出来。
- 将工具提供给小白，看他们能否正确使用功能，如果不能，将他们提出的问题的答案写在 prompt 中。
尽量减轻 LLM 负担，使用代码处理相关任务。
- 例如一个多轮工具调用的 workflow，需要使用同一个 order_id，那就不要在后续的调用中设置这个参数，而是通过代码来传递参数。
- 将总是按顺序被调用的函数组合在一起，减少 LLM 决策压力。
为了 LLM 调用准确性，减少初始可用的工具数量。
- 尝试使用不同数量的工具来评估 AI 应用的表现。
- 建议每轮开始时，限制可用工具数量在 20 以内。
- 使用 tool_search 隐藏工具中不常被使用的部分。

处理 Function calling

类似于后端的工作，把收到的请求路由到不同的程序来处理，然后将结果包装成符合格式的形式，然后将分析结果添加到 input 中，反馈给 LLM。

其他配置选项

默认情况下，模型会自行决定何时使用何种工具，以及使用多少个工具。你可以通过 tool_choice 参数来强制指定特定的行为。

auto：自动模式（默认）调用 0 个、1 个或多个函数。
required：要求至少调用一个函数。
forced function：强调必须调用某个特定函数，且只调用一次。
allowed tools：允许使用的工具，限制模型可用的工具范围。

并行函数调用

使用内置工具时无法实现并行函数调用。

模型可能在一轮调用中选择调用多个工具，可以将 parallel_tool_calls 设置为 false 来避免这种情况，这样就能保证恰好调用 0 或 1 个函数。

严格模式

将 strict 设置为 true 后，可以确保函数调用始终符合函数规范，而不是尽力符合规范，通常建议始终开启严格模式，同时该模式也带来了一些要求：

additionalProperties 必须为 parameters 中的每个对象设置为 false。
所有的 properties 字段必须标记为 required。
在可选字段前加 null 来标记该字段为可选项。

如果在请求中发送了 strict: true 但是架构不符合上述要求，请求会被拒绝。

Streaming 传输

通过流式处理，可以了解 LLM 的处理进度：即能够显示模型处理过程中调用了哪些函数，甚至实时展示函数的参数，只需要将 stream 设置为 true。

from openai import OpenAI

client = OpenAI()

tools = [{
    "type": "function",
    "name": "get_weather",
    "description": "Get current temperature for a given location.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "City and country e.g. Bogotá, Colombia"
            }
        },
        "required": [
            "location"
        ],
        "additionalProperties": False
    }
}]

stream = client.responses.create(
    model="gpt-5.5",
    input=[{"role": "user", "content": "What's the weather like in Paris today?"}],
    tools=tools,
    stream=True
)

for event in stream:
    print(event)

{"type":"response.output_item.added","response_id":"resp_1234xyz","output_index":0,"item":{"type":"function_call","id":"fc_1234xyz","call_id":"call_1234xyz","name":"get_weather","arguments":""}}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"{\""}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"location"}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"\":\""}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"Paris"}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":","}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":" France"}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"\"}"}
{"type":"response.function_call_arguments.done","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"arguments":"{\"location\":\"Paris, France\"}"}
{"type":"response.output_item.done","response_id":"resp_1234xyz","output_index":0,"item":{"type":"function_call","id":"fc_1234xyz","call_id":"call_1234xyz","name":"get_weather","arguments":"{\"location\":\"Paris, France\"}"}}

以下是代码示例，用来将多个 delta 对象合并为最终的 tool_call 对象：

final_tool_calls = {}

for event in stream:
    if event.type == "response.output_item.added":
        final_tool_calls[event.output_index] = event.item
    elif event.type == "response.function_call_arguments.delta":
        index = event.output_index

        if final_tool_calls[index]:
            final_tool_calls[index].arguments += event.delta

最终的 final_tool_calls[0]：

{
  "type": "function_call",
  "id": "fc_1234xyz",
  "call_id": "call_2345abc",
  "name": "get_weather",
  "arguments": "{\"location\":\"Paris, France\"}"
}

常见问题

Function calling 是让模型直接执行函数吗？

不是。模型通常只生成函数名和参数，真正执行函数的是你的程序。程序仍然需要做参数校验、权限判断、错误包装和结果回传。

strict mode 为什么还需要服务端校验？

严格模式能提高模型输出符合 schema 的概率，但它不是业务权限边界。路径、权限、枚举、资源归属、危险动作确认这些检查仍然应该在服务端或 Harness 层完成。

tool choice 应该什么时候使用 required？

当任务流程明确需要至少调用一个工具时可以使用 required。如果问题本身可能直接回答，长期强制调用工具会增加成本，也可能让模型做不必要的动作。

什么是 MCP

Wed, 24 Jun 2026 09:10:00 +0800

本文结论

MCP 是一种让 AI 应用连接外部工具、数据源和提示模板的开放协议。
它解决的是“AI 应用如何标准化访问外部上下文和能力”的问题。
MCP 常被类比为 AI 应用的 USB-C：不同应用和工具可以围绕同一套接口连接。
理解 MCP 时，要同时理解 Host、Client、Server，以及 Tools、Resources、Prompts 三类能力。

适合谁读

第一次听到 MCP，想快速理解它解决什么问题的人。
正在使用 Codex、Claude 等 AI 应用，想知道它们如何连接外部工具的人。
准备开发 MCP Server 或把 MCP 放进 Agent 工具体系里的人。

MCP 的定义

MCP 是 Model Context Protocol 的缩写，是一种用于将 AI 应用与外部系统相连的开源协议。借助 MCP，AI 应用可以获取所需的信息并完成各种任务。

通俗地讲，可以把 MCP 理解为 AI 应用的 “USB-C” 协议。USB-C 为电子设备提供标准化连接方式，MCP 则为 AI 应用访问工具、数据和提示模板提供标准化接口。

MCP 可以用来做什么

通过 MCP，智能体可以访问邮箱、日历、代码仓库、文件系统、数据库、设计工具和浏览器等外部系统。常见场景包括：

连接 GitHub，读取 issue、PR 或仓库内容。
连接数据库，通过自然语言分析数据。
连接文件系统，让 AI 应用读取或整理本地项目。
连接 Figma、Blender 等创作工具，把 AI 生成能力接入设计和 3D 工作流。
连接内部系统，让客服、运维或数据分析 Agent 使用企业上下文。

MCP 由哪些部分组成

理解 MCP 时，可以先看三层角色：

角色	作用
MCP Host	使用 MCP 能力的 AI 应用，例如 Codex 或 Claude Desktop
MCP Client	Host 内部负责连接某个 MCP Server 的组件
MCP Server	暴露工具、资源和提示模板的程序

MCP Server 通常提供三类能力：

能力	作用
Tools	可以被 AI 应用主动调用的动作，例如搜索、写入、调用 API
Resources	只读上下文或数据源，例如文件、文档、数据库记录
Prompts	可复用的任务模板，用来指导模型完成特定工作

常见误区

MCP 不是一个具体工具

MCP 是协议，不是某一个单独的应用。文件系统 Server、GitHub Server、数据库 Server 都可以是 MCP Server。

MCP 不等于 Agent Harness

MCP 提供标准化连接方式，但 Agent 仍然需要自己的 Harness 来处理权限、trace、错误恢复、上下文管理和 eval。

MCP 不会自动解决安全问题

MCP Server 暴露能力之后，仍然要认真设计权限、确认机制和审计。尤其是写文件、发请求、改数据库这类动作，不能只靠模型自觉。

AI Agent on Weiuou的博客

AI Agent 开发

一句话定义

推荐阅读顺序

核心概念表

学习路径

延伸阅读

MCP 学习路线

一句话定义

推荐阅读顺序

核心概念表

学习路径

延伸阅读

Function Calling

本文结论

适合谁读

什么是 Function calling

Function calling 定义与主要参数

最佳实践

处理 Function calling

其他配置选项

并行函数调用

严格模式

Streaming 传输

常见问题

Function calling 是让模型直接执行函数吗？

strict mode 为什么还需要服务端校验？

tool choice 应该什么时候使用 required？

延伸阅读

什么是 MCP

本文结论

适合谁读

MCP 的定义

MCP 可以用来做什么

MCP 由哪些部分组成

常见误区

MCP 不是一个具体工具

MCP 不等于 Agent Harness

MCP 不会自动解决安全问题

延伸阅读