在 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 什么是 AgentPi 如何重新定义它在 Pi 的语境中一个Agent是一个具有明确目标、能感知环境输入、进行思考推理、执行动作调用工具/函数并从中学习的自治程序。这与传统的代码补全工具如 Codex有本质区别。Codex 更像一个强大的“下一词预测器”它根据上下文生成代码片段但它没有“目标”的概念也不会为了达成目标而进行多步规划和自我修正。Pi 的“简”体现在其核心架构上。它通常不内置庞大的模型也不试图封装所有可能的工具。相反它提供了一个清晰的生命周期管理、工具调用规范和状态管理机制。开发者需要自己接入大模型如 OpenAI GPT、Claude、DeepSeek 等并定义 Agent 可以使用的工具函数。这种设计带来了几个关键优势透明可控每一步的思考过程、工具调用请求和结果都可以被记录和审查。灵活轻量没有强制的运行时或服务依赖可以很容易地集成到现有项目中。易于调试由于逻辑清晰当 Agent 行为异常时你可以像调试普通程序一样设置断点、查看变量、分析日志。1.2 Pi vs. Codex vs. Claude Code核心理念对比为了更清晰地理解 Pi 的定位我们将其与常见的工具进行对比特性维度Pi Agent (框架)Codex / GitHub Copilot (服务)Claude Code (桌面应用/插件)核心定位构建 Agent 的框架代码补全与生成服务集成式 AI 编程助手工作模式开发者定义目标、工具和推理逻辑Agent 自主规划执行。基于编辑器上下文实时提供单行或块级代码建议。在 IDE 内提供聊天、代码解释、生成、重构等综合功能。控制粒度极细。可控制每一步的思考、工具选择、参数验证。较粗。主要通过提示词Prompt和上下文影响输出。中等。通过界面交互但内部决策过程不透明。可扩展性极高。可自定义任何工具函数接入任何模型后端。低。功能由服务提供商决定。中等。通常支持有限的插件或自定义指令。复杂度初始配置复杂需要理解 Agent 概念和框架。即开即用复杂度低。开箱即用但高级功能可能需要学习。适用场景自动化工作流、复杂问题分解、需要多步交互和工具调用的任务。日常编码中的快速补全、生成样板代码、注释转代码。代码评审、调试、学习新代码库、中小型代码生成任务。简单来说如果你需要的是一个“听话且能干”的智能员工你需要告诉它目标并赋予它使用各种软件工具如搜索引擎、数据库客户端、命令行的能力那么你需要一个像 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, paramsparams, timeout10) 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}关键解释tool装饰器来自langchain它将普通 Python 函数标记为一个可供 Agent 调用的工具。装饰器会自动根据函数名、参数和文档字符串来生成工具的描述LLM 依靠这些描述来决定何时以及如何调用该工具。calculate工具我们明确指出了eval的安全风险。在实际生产 Agent 中你必须使用更安全的方式如ast.literal_eval配合白名单或sympy库来解析数学表达式。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_typeopenai): 创建一个简单的 ReAct Agent。 Args: llm_type: 指定使用的 LLM 类型openai 或 deepseek。 Returns: 一个配置好的 AgentExecutor 实例。 # 3. 初始化 LLM if llm_type.lower() openai: llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # temperature0 使输出更确定适合执行任务 elif llm_type.lower() deepseek: # 假设 DeepSeek 使用 OpenAI 兼容接口 llm ChatOpenAI( modeldeepseek-chat, # 模型名需根据 DeepSeek 文档调整 openai_api_keyos.getenv(DEEPSEEK_API_KEY), base_urlhttps://api.deepseek.com/v1, # DeepSeek API 端点 temperature0 ) 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(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) 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]})关键解释LLM 选择我们同时演示了 OpenAI 和 DeepSeek 的配置。关键在于ChatOpenAI类的base_url参数许多兼容 OpenAI API 的模型服务如 DeepSeek都可以通过这种方式接入。这体现了 Pi 框架的灵活性。ReAct 范式我们使用了create_react_agent它实现了 ReAct 框架。提示模板prompt_template严格规定了 LLM 的输出格式先思考Reason再决定行动Act并调用工具然后观察Observation结果如此循环直至得出最终答案。{agent_scratchpad}是一个占位符LangChain 会自动将之前的步骤历史填充进去。AgentExecutor这是实际运行 Agent 的组件。verboseTrue会打印出详细的思考和执行过程这对于调试和理解 Agent 行为至关重要。handle_parsing_errorsTrue能优雅地处理 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年被封为爵士。你看到了什么完整的 ReAct 循环Agent 展示了“思考 - 行动调用calculate- 观察 - 再思考 - 行动调用search_web- 观察 - 最终思考”的全过程。工具调用Agent 正确地选择了工具并传入了格式正确的参数JSON 字符串。结果整合Agent 将两个工具的结果整合成了一个连贯的最终答案。至此你已经成功构建并运行了一个极简但功能完整的 Pi Agent。它能够理解复杂指令、规划步骤、使用工具并总结答案。4. 核心机制详解与高级配置我们的第一个 Agent 跑通了但要真正掌握 Pi必须理解其内部机制和可配置项。4.1 Agent 的生命周期与状态管理在langchain的 AgentExecutor 中每一次invoke调用都经历以下阶段输入解析将用户输入和可能的对话历史格式化为初始提示。LLM 推理LLM 根据提示和“思维草稿”scratchpad生成下一步的文本思考、行动或最终答案。输出解析框架解析 LLM 的输出判断是“调用工具”还是“返回最终答案”。工具执行如果解析出工具调用则找到对应工具传入参数并执行。观察记录将工具执行的结果观察记录到思维草稿中。循环或终止将新的思维草稿作为上下文再次送入 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 插件概念结构插件前端TypeScript/JavaScript捕获用户输入、获取编辑器上下文、调用后端 API、显示结果。Pi Agent 后端Python就是我们上面构建的 Agent作为本地或远程服务运行处理来自插件的请求。这种架构将复杂的 AI 逻辑Pi Agent与编辑器界面VS Code解耦保持了 Pi 核心的简洁同时又能利用丰富的插件生态。5. 常见问题排查与调试指南构建和运行 Agent 时你一定会遇到各种问题。以下是系统性的排查路径。5.1 Agent 不调用工具直接回答问题现象对于明显需要工具如计算、搜索的问题Agent 直接用自己的知识生成答案而不触发工具调用。可能原因与解决方案提示模板不清晰LLM 没有理解必须使用工具。解决强化提示模板加入更多强制使用工具的示例并使用更明确的指令如“你必须使用上述工具之一来回答问题”。工具描述不准确工具的文档字符串没有清晰说明其用途和边界。解决重写工具的描述使其更精确并与 LLM 可能的知识领域区分开。LLM 温度Temperature过高temperature参数太高如 0.7会导致输出随机性大可能忽略工具使用指令。解决对于任务执行型 Agent将temperature设为 0 或接近 0如 0.1。工具名称模糊工具名称函数名最好能直观反映功能如calculate比tool1好得多。5.2 工具调用参数格式错误现象Agent 决定调用工具但输出的“行动输入”不是有效的 JSON或者参数名、类型与工具定义不匹配。可能原因与解决方案LLM 输出格式漂移即使有严格提示LLM 有时也会输出格式错误的 JSON。解决在AgentExecutor中设置handle_parsing_errorsTrue。你还可以编写自定义的输出解析器OutputParser来更鲁棒地处理这种情况。参数类型复杂如果工具参数是嵌套对象或列表LLM 更难生成正确的 JSON。解决尽量将工具参数设计为简单的字符串、数字或布尔值。如果必须复杂在工具描述中给出非常具体的 JSON 示例。检查verbose输出开启verboseTrue查看 LLM 生成的原始“行动输入”文本这能帮你定位是提示问题还是解析问题。5.3 网络或 API 错误现象工具调用失败特别是search_web这类依赖外部服务的工具。可能原因与解决方案网络连接问题解决检查本地网络为请求添加超时和重试机制。API 限制或失效示例中使用的 DuckDuckGo API 是公开的但可能有速率限制或变动。解决查看对应 API 的官方文档考虑使用更稳定的商业 API 或设置请求间隔。环境变量未设置对于需要 API Key 的模型如 OpenAI如果 Key 未正确设置会报认证错误。解决确认os.environ[“OPENAI_API_KEY”]已正确赋值或使用dotenv库从.env文件加载。5.4 性能与成本优化现象Agent 响应慢或使用付费模型时成本过高。可能原因与解决方案不必要的多轮对话Agent 陷入“思考-行动”循环迟迟不给出最终答案。解决在提示中限制最大思考步骤或在AgentExecutor中设置max_iterations和max_execution_time参数。工具执行慢某个工具如调用一个慢速 API拖慢了整体响应。解决优化工具内部逻辑或为工具调用设置超时。使用更经济的模型对于简单任务可以尝试使用更小、更快的模型如 GPT-3.5-turbo 而非 GPT-4。DeepSeek 等模型在成本和性能上可能有优势可以根据实际效果选择。6. 从演示到生产最佳实践与扩展方向将演示级的 Pi Agent 转化为一个稳定、可靠的生产级组件需要考虑更多因素。6.1 安全性与可靠性最佳实践实践领域演示代码中的风险生产级解决方案工具安全calculate使用不安全的eval。使用ast.literal_eval限制更多或sympy等专用库进行数学表达式求值。对所有用户输入进行严格的验证和清洗。API 密钥管理密钥硬编码在代码中。使用.env文件配合python-dotenv或专业的密钥管理服务如 AWS Secrets Manager。错误处理基础的工具错误处理。实现全局异常捕获和日志记录。为 Agent 设置优雅降级策略例如工具失败时返回友好提示而非崩溃。输入验证未对用户输入进行限制。对输入长度、内容防注入攻击进行校验。为不同工具设定明确的输入规范。依赖管理使用pip直接安装。使用requirements.txt或pyproject.toml精确锁定所有依赖版本。定期更新并测试依赖兼容性。6.2 可观测性与监控在生产中你必须知道你的 Agent 在做什么、表现如何。结构化日志不要只使用print。集成logging模块记录每次调用的输入、输出、使用的工具、耗时和任何错误。将日志输出到文件或日志聚合系统如 ELK。关键指标监控平均响应时间、工具调用成功率、各步骤耗时、Token 使用量如果计费等。链路追踪为每个用户会话或请求分配唯一 ID便于在日志中追踪完整的 ReAct 链条。6.3 扩展 Pi Agent 的能力“极简”不等于“功能弱”。Pi 的强大在于其可扩展性。你可以通过添加更多工具来赋予 Agent 超能力代码操作工具集成pyautogui或编辑器 API让 Agent 能直接修改代码文件。数据库工具连接数据库让 Agent 能查询、分析业务数据。文件系统工具读写文件、遍历目录进行简单的文件管理。自定义 API 工具封装内部业务系统 API让 Agent 成为业务流程的自动化助手。多模态工具集成图像识别、语音合成等模型处理图片、音频信息。每次新增工具都需要在提示模板的{tools}部分更新工具描述并确保 LLM 能通过描述理解新工具的用途。6.4 架构演进从单 Agent 到多 Agent 协作对于更复杂的任务可以考虑多 Agent 系统Multi-Agent System主管SupervisorAgent负责接收用户任务并将其分解为子任务分发给不同的专业 Agent。专业 Agent例如一个专门负责代码生成的CoderAgent一个专门负责代码审查的ReviewerAgent一个负责运行测试的TesterAgent。协调机制Agent 之间通过共享工作区如黑板模型或消息传递进行通信和协作。这种架构能处理极其复杂的任务但同时也引入了更高的复杂度和协调成本。Pi 的极简内核是构建此类复杂系统的良好基础因为每个 Agent 都可以保持简单和专注。通过本攻略你不仅学会了如何构建一个 Pi Agent更重要的是理解了其“大道至简”设计哲学背后的力量通过清晰的抽象Agent, Tool, LLM和可组合的架构你将获得远超单一代码补全工具的自动化能力。接下来尝试为你最常做的重复性开发任务创建一个专属工具并集成到你的 Pi Agent 中亲身体验它如何提升你的工作效率。