企业官网建设流程全解析

在 AI 编程助手领域，Codex 和 Claude Code 是许多开发者熟悉的名字，它们提供了强大的代码补全和生成能力。然而，对于追求极致简洁、轻量级且希望深度掌控工作流的开发者而言，一个名为Pi的 Agent 框架正悄然兴起。Pi 的设计哲学是“大道至简”，它不追求功能的大而全，而是聚焦于构建一个核心稳定、扩展灵活、易于理解和调试的智能体（Agent）系统。如果你厌倦了复杂臃肿的配置，希望从零开始理解 Agent 的运作机制，并亲手打造一个能与复杂模型交互的自动化工具，那么 Pi 将是一个值得深入研究的对象。

本文的目标是提供一个保姆级的全攻略，带你从零开始，理解 Pi Agent 的核心思想，完成环境搭建、核心功能实现、插件集成，并最终将其应用于实际开发场景。我们将重点对比 Pi 与 Codex、Claude Code 在设计理念和实现方式上的差异，解释为什么在某些场景下“极简”反而意味着“超越”。你将学习到的不是简单的 API 调用，而是如何构建一个可维护、可扩展、可调试的 Agent 系统骨架。

1. 理解 Pi Agent 的“大道至简”哲学

在深入代码之前，必须理解 Pi 框架的设计初衷。当前许多 AI 编程工具或 Agent 框架倾向于提供一个“黑盒”服务，开发者输入需求，得到结果，但中间的过程、决策逻辑和状态流转并不透明。当出现不符合预期的输出时，排查变得异常困难。

1.1 什么是 Agent？Pi 如何重新定义它？

在 Pi 的语境中，一个Agent是一个具有明确目标、能感知环境（输入）、进行思考（推理）、执行动作（调用工具/函数）并从中学习的自治程序。这与传统的代码补全工具（如 Codex）有本质区别。Codex 更像一个强大的“下一词预测器”，它根据上下文生成代码片段，但它没有“目标”的概念，也不会为了达成目标而进行多步规划和自我修正。

Pi 的“简”体现在其核心架构上。它通常不内置庞大的模型，也不试图封装所有可能的工具。相反，它提供了一个清晰的生命周期管理、工具调用规范和状态管理机制。开发者需要自己接入大模型（如 OpenAI GPT、Claude、DeepSeek 等），并定义 Agent 可以使用的工具（函数）。这种设计带来了几个关键优势：

• 透明可控：每一步的思考过程、工具调用请求和结果都可以被记录和审查。
• 灵活轻量：没有强制的运行时或服务依赖，可以很容易地集成到现有项目中。
• 易于调试：由于逻辑清晰，当 Agent 行为异常时，你可以像调试普通程序一样，设置断点、查看变量、分析日志。

1.2 Pi vs. Codex vs. Claude Code：核心理念对比

为了更清晰地理解 Pi 的定位，我们将其与常见的工具进行对比：

简单来说，如果你需要的是一个“听话且能干”的智能员工，你需要告诉它目标，并赋予它使用各种软件工具（如搜索引擎、数据库客户端、命令行）的能力，那么你需要一个像 Pi 这样的 Agent 框架。而 Codex 和 Claude Code 更像是坐在你旁边的“资深同事”，随时给你写代码的建议。

2. 环境准备与项目初始化

理解了理念，我们开始动手。Pi 不是一个有官方网站下载的单一软件，它更多是一种架构模式和代码库的统称。我们将基于 Python 语言，使用langchain库的核心概念来构建一个极简的 Pi Agent，因为langchain提供了优秀的 Agent 和 Tool 抽象，同时保持足够的灵活性。

2.1 基础环境要求

确保你的开发环境满足以下要求：

• Python: 版本 3.8 或更高。这是大多数现代 AI 库的基础要求。
• 包管理工具:pip或poetry。本文使用pip。
• 代码编辑器: VS Code 是绝佳选择，其丰富的插件生态（如 Python、Jupyter）能极大提升效率。
• 模型 API 密钥: 你需要一个大型语言模型的访问权限。我们将以OpenAI GPT和DeepSeek为例。你需要从相应平台获取 API Key。
  • OpenAI: 访问 platform.openai.com 注册并获取 Key。
  • DeepSeek: 访问 platform.deepseek.com 注册并获取 Key。

注意：保管好你的 API Key，不要将其直接提交到版本控制系统（如 Git）。务必使用环境变量或配置文件来管理。

2.2 创建项目与安装依赖

首先，创建一个干净的项目目录并初始化虚拟环境，这是管理 Python 项目依赖的最佳实践。

# 创建项目目录并进入 mkdir pi-simple-agent && cd pi-simple-agent # 创建虚拟环境（Python 3.8+） python -m venv venv # 激活虚拟环境 # 在 Windows 上: venv\Scripts\activate # 在 macOS/Linux 上: source venv/bin/activate # 激活后，命令行提示符前通常会出现 (venv) 标识

接下来，安装核心依赖。我们将安装langchain和openai库。langchain是构建 Agent 的脚手架，openai是其官方集成的 LLM 接口之一。

pip install langchain langchain-openai

为了后续示例，我们还需要安装一个用于计算和访问网络信息的工具库。

pip install requests

现在，你的项目基础环境已经就绪。目录结构目前很简单：

pi-simple-agent/ ├── venv/ # Python 虚拟环境目录（通常被 .gitignore 忽略） └── (后续创建的文件)

3. 构建第一个极简 Pi Agent：计算与信息查询

我们将构建一个能进行数学计算和查询网络信息的 Agent。这个 Agent 将展示如何定义工具、集成 LLM 并运行一个完整的思考-行动循环。

3.1 定义 Agent 的工具（Tools）

工具是 Agent 的手臂。没有工具，Agent 只是一个会思考的“大脑”，无法影响外部世界。我们创建两个简单的工具：一个计算器和一个网络查询器。

创建一个名为tools.py的文件：

# tools.py import math import requests from typing import Optional from langchain.tools import tool @tool def calculate(expression: str) -> str: """ 计算一个数学表达式的值。 支持加减乘除（+-*/）、乘方（**）、括号和常见数学函数如 sqrt, sin, cos。 例如: `calculate(\"2 + 3 * (4 - 1)\")` 或 `calculate(\"sqrt(16)\")` Args: expression: 一个字符串形式的数学表达式。 Returns: 计算结果的字符串表示，如果出错则返回错误信息。 """ # 安全警告：在生产环境中，直接 eval 用户输入是极度危险的！ # 这里仅用于演示。实际项目应使用 ast.literal_eval 或专用数学解析库（如 sympy）。 try: # 为数学表达式添加一些安全限制（非常基础） allowed_names = {k: v for k, v in math.__dict__.items() if not k.startswith("_")} allowed_names.update({"abs": abs, "round": round}) # 这是一个极简的演示，eval 仍存在风险。切勿在生产中用于处理不可信输入。 result = eval(expression, {"__builtins__": {}}, allowed_names) return str(result) except Exception as e: return f"计算错误: {e}" @tool def search_web(query: str, max_results: Optional[int] = 3) -> str: """ 使用 DuckDuckGo 即时答案 API 搜索网络信息。 这是一个简单、无需认证的 API，适合演示。 Args: query: 搜索查询词。 max_results: 返回摘要的最大数量，默认为3。 Returns: 搜索结果的摘要文本。如果 API 失败，返回错误信息。 """ try: url = "https://api.duckduckgo.com/" params = { "q": query, "format": "json", "no_html": 1, "skip_disambig": 1, } response = requests.get(url, params=params, timeout=10) data = response.json() # 提取抽象文本（AbstractText） abstract = data.get("AbstractText", "") if abstract: return f"关于 '{query}' 的摘要：{abstract}" else: # 如果没有摘要，尝试返回相关主题 related_topics = data.get("RelatedTopics", []) snippets = [] for topic in related_topics[:max_results]: text = topic.get("Text", "") if text: snippets.append(text) if snippets: return f"未找到直接摘要，相关信息：{' '.join(snippets[:max_results])}" else: return f"未找到关于 '{query}' 的明确信息。" except requests.RequestException as e: return f"网络请求失败: {e}" except Exception as e: return f"处理搜索结果时出错: {e}"

关键解释：

1. @tool装饰器来自langchain，它将普通 Python 函数标记为一个可供 Agent 调用的工具。装饰器会自动根据函数名、参数和文档字符串来生成工具的描述，LLM 依靠这些描述来决定何时以及如何调用该工具。
2. calculate工具：我们明确指出了eval的安全风险。在实际生产 Agent 中，你必须使用更安全的方式（如ast.literal_eval配合白名单，或sympy库）来解析数学表达式。
3. search_web工具：我们使用了一个无需密钥的公共 API。对于更复杂或商业化的需求，你可能需要集成 Serper、Google Search API 等。

3.2 配置 LLM 与创建 Agent

接下来，我们创建 Agent 的核心运行逻辑。创建一个名为agent_core.py的文件。

首先，设置环境变量来存储你的 API Key（更安全的方式是使用.env文件，这里为演示方便直接设置）。

# agent_core.py import os from langchain_openai import ChatOpenAI # 注意：DeepSeek 可能需要使用 ChatOpenAI 兼容接口或特定的 LangChain 集成。 # 假设 DeepSeek 提供了与 OpenAI API 兼容的端点。 from langchain.agents import create_react_agent, AgentExecutor from langchain.prompts import PromptTemplate from langchain.tools.render import render_text_description # 1. 设置 API Key (在实际项目中，请从环境变量或配置文件中读取) os.environ["OPENAI_API_KEY"] = "你的-OpenAI-API-Key" # 如果需要使用 DeepSeek，可能需要设置不同的环境变量和 base_url # os.environ["DEEPSEEK_API_KEY"] = "你的-DeepSeek-API-Key" # 2. 导入我们定义的工具 from tools import calculate, search_web def create_agent(llm_type="openai"): """ 创建一个简单的 ReAct Agent。 Args: llm_type: 指定使用的 LLM 类型，'openai' 或 'deepseek'。 Returns: 一个配置好的 AgentExecutor 实例。 """ # 3. 初始化 LLM if llm_type.lower() == "openai": llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0) # temperature=0 使输出更确定，适合执行任务 elif llm_type.lower() == "deepseek": # 假设 DeepSeek 使用 OpenAI 兼容接口 llm = ChatOpenAI( model="deepseek-chat", # 模型名需根据 DeepSeek 文档调整 openai_api_key=os.getenv("DEEPSEEK_API_KEY"), base_url="https://api.deepseek.com/v1", # DeepSeek API 端点 temperature=0 ) else: raise ValueError(f"不支持的 LLM 类型: {llm_type}") # 4. 准备工具列表 tools = [calculate, search_web] # 5. 定义 ReAct 提示模板 # ReAct (Reason + Act) 是一种让 LLM 交替进行“思考”和“行动”的范式。 prompt_template = """你是一个乐于助人的助手，可以回答问题和执行任务。 你可以使用以下工具： {tools} 使用以下格式： 问题：你需要回答的输入问题 思考：你需要思考如何逐步解决问题。你可以使用工具。 行动：要采取的行动，应该是以下之一 [{tool_names}] 行动输入：行动的输入，必须是一个有效的 JSON 字符串 观察：行动的结果 ... (这个 思考/行动/观察 循环可以重复多次) 思考：我现在知道了最终答案 最终答案：对原始问题的最终答案 开始！ 问题：{input} 思考：{agent_scratchpad}""" prompt = PromptTemplate.from_template(prompt_template) # 6. 创建 Agent 和 Executor agent = create_react_agent(llm, tools, prompt) agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True, handle_parsing_errors=True) return agent_executor if __name__ == "__main__": # 测试 Agent agent = create_agent("openai") # 或 "deepseek" question = "请先计算圆周率 pi 的平方根，然后搜索一下牛顿的生平简介。" print(f"问题: {question}") print("-" * 50) result = agent.invoke({"input": question}) print("\n" + "="*50) print(f"最终答案: {result['output']}")

关键解释：

1. LLM 选择：我们同时演示了 OpenAI 和 DeepSeek 的配置。关键在于ChatOpenAI类的base_url参数，许多兼容 OpenAI API 的模型服务（如 DeepSeek）都可以通过这种方式接入。这体现了 Pi 框架的灵活性。
2. ReAct 范式：我们使用了create_react_agent，它实现了 ReAct 框架。提示模板（prompt_template）严格规定了 LLM 的输出格式：先思考（Reason），再决定行动（Act）并调用工具，然后观察（Observation）结果，如此循环直至得出最终答案。{agent_scratchpad}是一个占位符，LangChain 会自动将之前的步骤历史填充进去。
3. AgentExecutor：这是实际运行 Agent 的组件。verbose=True会打印出详细的思考和执行过程，这对于调试和理解 Agent 行为至关重要。handle_parsing_errors=True能优雅地处理 LLM 输出格式不符合预期的情况。

3.3 运行与验证

现在，运行我们的第一个 Agent。

# 确保在虚拟环境中，并且当前目录是 pi-simple-agent python agent_core.py

如果一切配置正确，你将看到类似以下的输出（具体内容因模型和问题而异）：

问题：请先计算圆周率 pi 的平方根，然后搜索一下牛顿的生平简介。 -------------------------------------------------- > 进入新的 AgentExecutor 链... 思考：用户要求做两件事：1. 计算圆周率 pi 的平方根。2. 搜索牛顿的生平简介。我需要按顺序完成。首先，计算 pi 的平方根。我可以使用计算工具。 行动：calculate 行动输入：{"expression": "math.sqrt(math.pi)"} 观察：1.7724538509055159 思考：第一步计算完成，结果是约 1.77245。现在进行第二步：搜索牛顿的生平简介。我需要使用网络搜索工具。 行动：search_web 行动输入：{"query": "艾萨克·牛顿 生平 简介", "max_results": 3} 观察：关于 '艾萨克·牛顿 生平 简介' 的摘要：艾萨克·牛顿爵士（1643年1月4日－1727年3月31日）是一位英国数学家、物理学家、天文学家、自然哲学家和炼金术士。他被广泛认为是科学史上最有影响力的人物之一。牛顿在《自然哲学的数学原理》中发表了万有引力定律和牛顿运动定律，奠定了经典力学的基础。他还与戈特弗里德·威廉·莱布尼茨分享了发展微积分学的荣誉。牛顿还展示了棱镜可以将白光分解为彩色光谱，并发展了色彩理论。他于1705年被安妮女王封为爵士。 思考：我已经完成了计算和搜索，现在可以给出最终答案。 最终答案：圆周率 π 的平方根约为 1.77245。艾萨克·牛顿爵士（1643-1727）是英国数学家、物理学家、天文学家，被誉为科学史上最具影响力的人物之一。他提出了万有引力定律和牛顿运动定律，奠定了经典力学，并与莱布尼茨共同发展了微积分。他还对光学有重要贡献，如用棱镜分解白光。1705年被封为爵士。 > 链结束。 ================================================== 最终答案：圆周率 π 的平方根约为 1.77245。艾萨克·牛顿爵士（1643-1727）是英国数学家、物理学家、天文学家，被誉为科学史上最具影响力的人物之一。他提出了万有引力定律和牛顿运动定律，奠定了经典力学，并与莱布尼茨共同发展了微积分。他还对光学有重要贡献，如用棱镜分解白光。1705年被封为爵士。

你看到了什么？

1. 完整的 ReAct 循环：Agent 展示了“思考 -> 行动（调用calculate）-> 观察 -> 再思考 -> 行动（调用search_web）-> 观察 -> 最终思考”的全过程。
2. 工具调用：Agent 正确地选择了工具，并传入了格式正确的参数（JSON 字符串）。
3. 结果整合：Agent 将两个工具的结果整合成了一个连贯的最终答案。

至此，你已经成功构建并运行了一个极简但功能完整的 Pi Agent。它能够理解复杂指令、规划步骤、使用工具并总结答案。

4. 核心机制详解与高级配置

我们的第一个 Agent 跑通了，但要真正掌握 Pi，必须理解其内部机制和可配置项。

4.1 Agent 的生命周期与状态管理

在langchain的 AgentExecutor 中，每一次invoke调用都经历以下阶段：

1. 输入解析：将用户输入和可能的对话历史格式化为初始提示。
2. LLM 推理：LLM 根据提示和“思维草稿”（scratchpad）生成下一步的文本（思考、行动或最终答案）。
3. 输出解析：框架解析 LLM 的输出，判断是“调用工具”还是“返回最终答案”。
4. 工具执行：如果解析出工具调用，则找到对应工具，传入参数并执行。
5. 观察记录：将工具执行的结果（观察）记录到思维草稿中。
6. 循环或终止：将新的思维草稿作为上下文，再次送入 LLM 进行下一轮推理，直到 LLM 输出“最终答案”。

这个循环的核心是agent_scratchpad变量，它保存了所有历史步骤，是 Agent 拥有“记忆”和进行多步规划的关键。

4.2 工具（Tool）的设计规范

一个设计良好的工具是 Agent 高效工作的基础。遵循以下规范：

• 清晰的文档字符串（Docstring）：这是 LLM 理解工具功能的唯一依据。必须清晰描述功能、参数和返回值。
• 强类型参数：使用 Python 类型注解（如str,int,Optional[int]）。这有助于 LangChain 生成更准确的工具 Schema。
• 健壮的错误处理：工具内部必须捕获异常，并返回明确的错误信息，而不是抛出异常导致整个 Agent 崩溃。
• 单一职责：一个工具只做一件事。不要创建一个“万能”工具。例如，将“计算”和“搜索”分开。
• 安全性：这是重中之重。尤其是执行系统命令、访问数据库、处理用户输入的工具，必须进行严格的输入验证和权限控制。

4.3 提示工程（Prompt Engineering）优化

我们之前使用的prompt_template是 LangChain 内置 ReAct 提示的简化版。在实际项目中，你可能需要优化它以提高性能：

• 提供更多示例（Few-Shot）：在提示中加入几个完整的“问题-思考-行动-观察-答案”的例子，能显著提升 Agent 遵循格式和正确使用工具的能力。
• 限制工具使用范围：在提示中明确说明工具的适用场景和限制。例如，“calculate工具仅用于数学计算，不要用它处理文本”。
• 设定 Agent 角色：“你是一个专业的数学和科学助手”，这样的角色设定能引导 LLM 生成更专业的输出。

一个增强版的提示模板可能如下所示：

enhanced_prompt = PromptTemplate.from_template(""" 你是一个专业的数学与信息查询助手。你的目标是准确、高效地回答问题。 你可以使用以下工具： {tools} 请严格按照以下格式回应： 问题：用户的问题 思考：分析问题，决定是否需要以及使用哪个工具。如果需要多个步骤，一步步规划。 行动：工具名称，必须是 [{tool_names}] 中的一个 行动输入：工具的输入，必须是有效的 JSON 字符串 观察：工具返回的结果 ... (重复思考/行动/观察直到问题解决) 思考：根据所有观察，我得到了最终答案。 最终答案：清晰、简洁地回答原始问题。 示例1： 问题：10 的阶乘是多少？ 思考：这是一个数学计算问题，可以使用 calculate 工具。 行动：calculate 行动输入：{{"expression": "math.factorial(10)"}} 观察：3628800 思考：我现在知道了最终答案。 最终答案：10 的阶乘是 3,628,800。 示例2： 问题：谁发明了电话？ 思考：这是一个事实查询问题，可以使用 search_web 工具。 行动：search_web 行动输入：{{"query": "电话 发明者", "max_results": 1}} 观察：关于 '电话 发明者' 的摘要：电话通常被认为是安东尼奥·梅乌奇、亚历山大·格拉汉姆·贝尔和伊莱沙·格雷等人发明的，其中贝尔在1876年获得了第一个实用电话的美国专利。 思考：我现在知道了最终答案。 最终答案：电话的发明通常归功于亚历山大·格拉汉姆·贝尔，他于1876年获得了第一个实用电话的美国专利，但安东尼奥·梅乌奇和伊莱沙·格雷等人也做出了重要贡献。 现在，开始处理真实问题： 问题：{input} {agent_scratchpad} """)

4.4 接入 Claude Code 或 VS Code 插件生态

“Pi 大道至简”的理念也体现在其集成能力上。我们的 Pi Agent 核心是一个 Python 程序，这意味着它可以被多种方式调用：

• 作为 CLI 工具：将agent_core.py包装成命令行工具，接受用户输入。
• 作为 REST API 服务：使用 FastAPI 或 Flask 将 Agent 封装成 HTTP 端点，供其他应用调用。
• 集成到 VS Code 插件中：这是实现类似 Claude Code 体验的关键。你可以创建一个 VS Code 插件，在后台运行这个 Python Agent，并将编辑器的代码上下文、用户指令作为输入传给 Agent，再将 Agent 的输出（代码建议、解释等）展示在编辑器中。

一个极简的 VS Code 插件概念结构：

1. 插件前端（TypeScript/JavaScript）：捕获用户输入、获取编辑器上下文、调用后端 API、显示结果。
2. Pi Agent 后端（Python）：就是我们上面构建的 Agent，作为本地或远程服务运行，处理来自插件的请求。

这种架构将复杂的 AI 逻辑（Pi Agent）与编辑器界面（VS Code）解耦，保持了 Pi 核心的简洁，同时又能利用丰富的插件生态。

5. 常见问题排查与调试指南

构建和运行 Agent 时，你一定会遇到各种问题。以下是系统性的排查路径。

5.1 Agent 不调用工具，直接回答问题

现象：对于明显需要工具（如计算、搜索）的问题，Agent 直接用自己的知识生成答案，而不触发工具调用。可能原因与解决方案：

1. 提示模板不清晰：LLM 没有理解必须使用工具。解决：强化提示模板，加入更多强制使用工具的示例，并使用更明确的指令（如“你必须使用上述工具之一来回答问题”）。
2. 工具描述不准确：工具的文档字符串没有清晰说明其用途和边界。解决：重写工具的描述，使其更精确，并与 LLM 可能的知识领域区分开。
3. LLM 温度（Temperature）过高：temperature参数太高（如 >0.7）会导致输出随机性大，可能忽略工具使用指令。解决：对于任务执行型 Agent，将temperature设为 0 或接近 0（如 0.1）。
4. 工具名称模糊：工具名称（函数名）最好能直观反映功能，如calculate比tool1好得多。

5.2 工具调用参数格式错误

现象：Agent 决定调用工具，但输出的“行动输入”不是有效的 JSON，或者参数名、类型与工具定义不匹配。可能原因与解决方案：

1. LLM 输出格式漂移：即使有严格提示，LLM 有时也会输出格式错误的 JSON。解决：在AgentExecutor中设置handle_parsing_errors=True。你还可以编写自定义的输出解析器（OutputParser）来更鲁棒地处理这种情况。
2. 参数类型复杂：如果工具参数是嵌套对象或列表，LLM 更难生成正确的 JSON。解决：尽量将工具参数设计为简单的字符串、数字或布尔值。如果必须复杂，在工具描述中给出非常具体的 JSON 示例。
3. 检查verbose输出：开启verbose=True，查看 LLM 生成的原始“行动输入”文本，这能帮你定位是提示问题还是解析问题。

5.3 网络或 API 错误

现象：工具调用失败，特别是search_web这类依赖外部服务的工具。可能原因与解决方案：

1. 网络连接问题：解决：检查本地网络，为请求添加超时和重试机制。
2. API 限制或失效：示例中使用的 DuckDuckGo API 是公开的，但可能有速率限制或变动。解决：查看对应 API 的官方文档，考虑使用更稳定的商业 API 或设置请求间隔。
3. 环境变量未设置：对于需要 API Key 的模型（如 OpenAI），如果 Key 未正确设置，会报认证错误。解决：确认os.environ[“OPENAI_API_KEY”]已正确赋值，或使用dotenv库从.env文件加载。

5.4 性能与成本优化

现象：Agent 响应慢，或使用付费模型时成本过高。可能原因与解决方案：

1. 不必要的多轮对话：Agent 陷入“思考-行动”循环，迟迟不给出最终答案。解决：在提示中限制最大思考步骤，或在AgentExecutor中设置max_iterations和max_execution_time参数。
2. 工具执行慢：某个工具（如调用一个慢速 API）拖慢了整体响应。解决：优化工具内部逻辑，或为工具调用设置超时。
3. 使用更经济的模型：对于简单任务，可以尝试使用更小、更快的模型（如 GPT-3.5-turbo 而非 GPT-4）。DeepSeek 等模型在成本和性能上可能有优势，可以根据实际效果选择。

6. 从演示到生产：最佳实践与扩展方向

将演示级的 Pi Agent 转化为一个稳定、可靠的生产级组件，需要考虑更多因素。

6.1 安全性与可靠性最佳实践

6.2 可观测性与监控

在生产中，你必须知道你的 Agent 在做什么、表现如何。

• 结构化日志：不要只使用print。集成logging模块，记录每次调用的输入、输出、使用的工具、耗时和任何错误。将日志输出到文件或日志聚合系统（如 ELK）。
• 关键指标：监控平均响应时间、工具调用成功率、各步骤耗时、Token 使用量（如果计费）等。
• 链路追踪：为每个用户会话或请求分配唯一 ID，便于在日志中追踪完整的 ReAct 链条。

6.3 扩展 Pi Agent 的能力

“极简”不等于“功能弱”。Pi 的强大在于其可扩展性。你可以通过添加更多工具来赋予 Agent 超能力：

1. 代码操作工具：集成pyautogui或编辑器 API，让 Agent 能直接修改代码文件。
2. 数据库工具：连接数据库，让 Agent 能查询、分析业务数据。
3. 文件系统工具：读写文件、遍历目录，进行简单的文件管理。
4. 自定义 API 工具：封装内部业务系统 API，让 Agent 成为业务流程的自动化助手。
5. 多模态工具：集成图像识别、语音合成等模型，处理图片、音频信息。

每次新增工具，都需要在提示模板的{tools}部分更新工具描述，并确保 LLM 能通过描述理解新工具的用途。

6.4 架构演进：从单 Agent 到多 Agent 协作

对于更复杂的任务，可以考虑多 Agent 系统（Multi-Agent System）：

• 主管（Supervisor）Agent：负责接收用户任务，并将其分解为子任务，分发给不同的专业 Agent。
• 专业 Agent：例如，一个专门负责代码生成的CoderAgent，一个专门负责代码审查的ReviewerAgent，一个负责运行测试的TesterAgent。
• 协调机制：Agent 之间通过共享工作区（如黑板模型）或消息传递进行通信和协作。

这种架构能处理极其复杂的任务，但同时也引入了更高的复杂度和协调成本。Pi 的极简内核是构建此类复杂系统的良好基础，因为每个 Agent 都可以保持简单和专注。

通过本攻略，你不仅学会了如何构建一个 Pi Agent，更重要的是理解了其“大道至简”设计哲学背后的力量：通过清晰的抽象（Agent, Tool, LLM）和可组合的架构，你将获得远超单一代码补全工具的自动化能力。接下来，尝试为你最常做的重复性开发任务创建一个专属工具，并集成到你的 Pi Agent 中，亲身体验它如何提升你的工作效率。