在实际 AI 开发和应用中直接调用大模型 API 往往只是第一步。真正让 AI 产生稳定、可控、可复用的价值需要将提示词Prompt与 AI 代理AI Agents结合起来构建能够理解复杂指令、执行多步任务、并具备一定自主决策能力的智能体。Claude 和 Codex 作为两类具有代表性的先进模型其代理模式的实践方式各有侧重。本文将围绕如何有效地配对提示词与 Claude/Codex AI 代理这一核心议题从概念理解、环境搭建、核心模式实现、到生产级最佳实践提供一个完整的工程指南。Claude 模型由 Anthropic 公司开发以其强大的对话能力、对指令的精准理解和良好的安全性设计著称。Codex 模型则由 OpenAI 推出是 GPT-3 的后代特别擅长理解和生成代码是 GitHub Copilot 的核心。所谓 AI 代理是指一个能够感知环境、进行决策并执行动作以达成目标的系统。当我们将精心设计的提示词注入这些强大的模型就能“激活”它们使其成为能够完成特定任务的代理。本文将带你完成从零构建一个基础 AI 代理的完整流程。你会学习到如何为 Claude 和 Codex 设计有效的提示词框架如何通过代码调用它们并处理响应以及如何构建一个能够进行多轮对话、具备工具使用能力或甚至能进行简单推理的代理系统。我们还将深入探讨在真实项目中最容易遇到的陷阱例如上下文管理、成本控制、错误处理等并提供具体的解决方案。1. 理解 AI 代理的核心提示词与模型的协同在深入代码之前必须清晰理解提示词Prompt与 AI 代理Agent之间的关系。这不是简单的“问与答”而更像是在为模型定义角色、任务、边界和交互规则。1.1 提示词作为代理的“操作手册”一个基础的提示词可能只是一个问题。但一个用于驱动代理的提示词则是一个复杂的规范。它通常包含以下几个部分系统角色设定明确告知模型它在当前会话中扮演的角色例如“你是一个专业的 Python 代码助手”或“你是一个能够分析用户需求并生成 SQL 查询的智能代理”。任务目标清晰、无歧义地描述需要完成的任务。步骤约束如果任务需要多步完成提示词可以规定步骤顺序或逻辑。输出格式要求指定模型返回数据的格式如 JSON、Markdown 或特定的代码结构。上下文规则说明如何利用之前的对话历史以及哪些信息是重要的。这种结构化的提示词将通用的语言模型“塑造”成了一个专用于特定任务的代理。1.2 Claude 与 Codex 代理的典型差异虽然核心思想一致但由于训练数据和设计目标的差异Claude 和 Codex 在构建代理时各有侧重。Claude 代理更擅长处理需要复杂逻辑推理、多轮对话、内容创作和安全合规的任务。它的强项在于理解模糊的人类指令并将其具体化。例如构建一个“产品需求分析代理”或“内容安全审核代理”Claude 是很好的选择。Codex 代理核心能力是代码生成、解释、补全和调试。因此Codex 代理天生适合构建“代码助手”、“自动化脚本生成器”、“SQL 查询生成器”或“代码审查工具”。它对编程语言的语法和语义有深刻的理解。理解这一差异是正确选型的第一步。一个需要与用户深入讨论需求再生成代码的场景可能更适合用 Claude 作为主代理在需要时调用 Codex 完成代码生成子任务。1.3 代理的基本工作流程一个典型的 AI 代理工作流程可以抽象为以下循环感知接收用户输入或环境信息。决策模型在提示词的引导下分析当前信息决定要执行的动作或要生成的内容。执行模型输出结果。在高级代理中这可能包括调用外部工具如 API、数据库。观察获取执行结果并将其作为新的上下文。循环重复步骤 2-4直到任务完成或达到终止条件。我们的目标就是用代码实现这个循环并将 Claude 或 Codex 模型作为决策的核心。2. 环境准备与 API 配置构建 AI 代理的第一步是准备好开发环境并获得模型 API 的访问权限。2.1 获取 API 密钥Claude API访问 Anthropic 官方开发者平台注册账号并申请 API 密钥。通常需要等待审核通过。Codex APICodex 模型通过 OpenAI API 提供。访问 OpenAI 平台注册账号并生成 API 密钥。请注意OpenAI API 是付费服务需要绑定支付方式。重要API 密钥是高度敏感信息绝不能直接硬编码在代码中或提交到版本控制系统如 Git。务必使用环境变量或安全的配置文件管理。2.2 Python 环境搭建我们将使用 Python 作为主要开发语言。确保你的环境满足以下要求Python 3.8 或更高版本。包管理工具pip。首先创建并激活一个虚拟环境这是一个良好的实践可以隔离项目依赖。# 创建虚拟环境 python -m venv ai_agent_venv # 激活虚拟环境 (Linux/macOS) source ai_agent_venv/bin/activate # 激活虚拟环境 (Windows PowerShell) .\ai_agent_venv\Scripts\Activate.ps12.3 安装必要的库根据你选择的模型安装对应的官方 SDK 或其他辅助库。# 如果你主要使用 Claude pip install anthropic # 如果你主要使用 OpenAI (Codex) pip install openai # 通用工具库用于处理环境变量和 JSON pip install python-dotenv requests2.4 配置 API 密钥创建一个名为.env的文件在你的项目根目录下用于存储环境变量。# .env 文件内容 ANTHROPIC_API_KEYyour_anthropic_api_key_here OPENAI_API_KEYyour_openai_api_key_here然后在 Python 代码中安全地加载这些密钥。# config.py import os from dotenv import load_dotenv load_dotenv() # 加载 .env 文件中的环境变量 ANTHROPIC_API_KEY os.getenv(ANTHROPIC_API_KEY) OPENAI_API_KEY os.getenv(OPENAI_API_KEY) # 检查密钥是否成功加载 if not ANTHROPIC_API_KEY: print(警告: 未找到 ANTHROPIC_API_KEY) if not OPENAI_API_KEY: print(警告: 未找到 OPENAI_API_KEY)3. 构建基础代理从单次调用到会话管理现在我们开始编写代码实现最基本的代理交互并逐步增加会话管理能力。3.1 实现一个简单的 Claude 代理以下代码展示了一个最简单的 Claude 代理它接收一个提示词返回模型生成的文本。# claude_agent_simple.py import anthropic from config import ANTHROPIC_API_KEY def simple_claude_agent(prompt: str, model: str claude-3-sonnet-20240229) - str: 一个简单的 Claude 代理函数。 Args: prompt: 发送给 Claude 的完整提示词。 model: 使用的 Claude 模型版本。 Returns: Claude 模型生成的文本内容。 client anthropic.Anthropic(api_keyANTHROPIC_API_KEY) message client.messages.create( modelmodel, max_tokens1024, messages[ { role: user, content: prompt } ] ) # 提取并返回模型的回复内容 return message.content[0].text # 使用示例 if __name__ __main__: user_query 请用 Python 写一个函数计算斐波那契数列的第 n 项。 response simple_claude_agent(user_query) print(Claude 的回答) print(response)3.2 实现一个简单的 Codex 代理Codex 代理的调用方式与 Claude 类似但通过 OpenAI 的 API。以下示例使用gpt-3.5-turbo-instructCodex 的替代品OpenAI 已推荐使用此模型进行代码补全任务。# codex_agent_simple.py import openai from config import OPENAI_API_KEY def simple_codex_agent(prompt: str, model: str gpt-3.5-turbo-instruct) - str: 一个简单的 Codex 风格代理函数用于代码生成。 Args: prompt: 代码生成指令。 model: 使用的模型。 Returns: 模型生成的代码。 openai.api_key OPENAI_API_KEY response openai.Completions.create( modelmodel, promptprompt, max_tokens500, temperature0.2 # 温度值较低生成结果更确定适合代码 ) return response.choices[0].text.strip() # 使用示例 if __name__ __main__: code_prompt # 根据以下要求编写一个 Python 函数 # 1. 函数名为 validate_email # 2. 接收一个字符串参数 email # 3. 使用正则表达式验证该字符串是否为有效的电子邮件格式 # 4. 返回布尔值True 表示有效False 表示无效 import re def validate_email(email): generated_code simple_codex_agent(code_prompt) print(生成的代码) print(generated_code)3.3 为代理添加会话记忆多轮对话单次调用的代理能力有限。真正的代理需要记住对话历史实现连贯的多轮交互。下面的ConversationalAgent类实现了基本的会话记忆功能。# conversational_agent.py import anthropic from typing import List, Dict from config import ANTHROPIC_API_KEY class ConversationalAgent: 一个具备会话记忆能力的 AI 代理基类。 def __init__(self, system_prompt: str, model: str claude-3-sonnet-20240229): 初始化代理。 Args: system_prompt: 定义代理角色和能力的系统提示词。 model: 使用的模型名称。 self.client anthropic.Anthropic(api_keyANTHROPIC_API_KEY) self.model model self.conversation_history: List[Dict] [] # 将系统提示词作为第一条消息加入历史 if system_prompt: self.conversation_history.append({role: user, content: system_prompt}) # 这里可以添加一条模拟的助理回复或者等待第一次用户输入后再获取回复。 # 更常见的做法是将系统提示词放在每次请求的“系统”角色消息中但Anthropic Messages API 使用方式略有不同。 # 我们采用另一种方式将系统提示词与用户消息组合。 def _build_messages(self, user_input: str) - List[Dict]: 构建发送给 API 的消息列表。 # 对于 Claude我们可以将系统提示词与用户输入结合或者使用专门的系统消息如果API支持。 # 这里我们采用一种简单方法将系统提示词作为历史的一部分。 # 在实际最新API中可以使用 system 参数。 messages self.conversation_history.copy() messages.append({role: user, content: user_input}) return messages def get_response(self, user_input: str) - str: 处理用户输入并返回代理的回复。 messages_for_api self._build_messages(user_input) try: message self.client.messages.create( modelself.model, max_tokens1024, messagesmessages_for_api ) assistant_reply message.content[0].text # 更新对话历史 self.conversation_history.append({role: user, content: user_input}) self.conversation_history.append({role: assistant, content: assistant_reply}) return assistant_reply except Exception as e: return f抱歉代理在处理您的请求时出现了错误{str(e)} def clear_history(self): 清空对话历史。 self.conversation_history.clear() # 使用示例创建一个代码助手代理 if __name__ __main__: system_prompt 你是一个专业的Python代码助手。你的职责是 1. 根据用户需求生成准确、高效的Python代码。 2. 解释代码的逻辑和关键部分。 3. 如果用户代码有错误帮助诊断并提出修改建议。 请用中文与用户交流。 code_agent ConversationalAgent(system_promptsystem_prompt) print(代码助手代理已启动。输入退出来结束对话。) while True: user_input input(\n您: ) if user_input.lower() in [退出, exit, quit]: break response code_agent.get_response(user_input) print(f\n助手: {response})这个代理现在可以记住整个对话上下文用户可以进行如“帮我写一个函数” - “现在为这个函数添加注释” - “如果输入不是数字怎么办”这样的连贯对话。4. 高级模式工具使用与推理代理基础代理只能生成文本。高级代理常被称为“智能体”或“Agents”能够理解何时需要以及如何使用外部工具如计算器、搜索引擎、数据库来完成任务。这通常通过让模型生成结构化的响应如 JSON来实现然后代码解析这个响应并执行相应动作。4.1 设计工具使用的工作流程其核心工作流程如下用户输入代理接收用户查询。模型思考模型分析查询判断是否需要使用工具、使用哪个工具、以及需要什么参数。生成结构化请求模型输出一个预定义格式的请求例如{action: search_web, parameters: {query: Python latest features}}。代码执行工具代理的代码解析这个请求调用相应的工具函数如调用 Google Search API。获取工具结果工具返回结果如搜索到的网页摘要。模型合成答案将工具结果作为新上下文再次发送给模型让模型合成最终答案回复给用户。4.2 实现一个具备计算能力的代理下面是一个简化版的工具使用代理示例它让 Claude 能够使用一个计算器工具。# tool_using_agent.py import anthropic import json import re from config import ANTHROPIC_API_KEY class CalculatorAgent: 一个可以使用计算器工具的 AI 代理。 def __init__(self): self.client anthropic.Anthropic(api_keyANTHROPIC_API_KEY) self.model claude-3-sonnet-20240229 def _calculate(self, expression: str) - float: 一个安全的计算器函数。注意在生产环境中使用 eval 是危险的这里仅作演示。 # 严重警告在实际生产环境中直接使用 eval 处理用户输入是极其危险的可能导致代码执行漏洞。 # 这里为了演示进行了极简单的过滤。真实场景应使用 AST 解析或专门的数学表达式库如 numexpr。 # 只允许数字、基本运算符和括号 if re.match(r^[\d\\-\*\/\(\)\.\s]$, expression): try: return eval(expression) except: return None else: return None def run(self, user_query: str) - str: 运行代理处理用户查询。 # 系统提示词明确告诉模型可以使用工具以及格式。 system_prompt 你是一个智能助手可以回答问题和进行数学计算。 当你遇到需要计算数学表达式的问题时你可以使用计算器工具。 为了使用工具请严格按照以下 JSON 格式回复 { thoughts: 你的思考过程解释为什么需要计算, action: calculate, // 或者 final_answer parameters: { expression: 待计算的数学表达式例如 2 3 * (10 - 4) // 当 action 为 calculate 时需要 }, final_answer: 直接给用户的最终答案 // 当 action 为 final_answer 时需要 } 请只输出这个 JSON 对象不要有其他任何文字。 # 构建消息 message self.client.messages.create( modelself.model, max_tokens1024, systemsystem_prompt, # 使用 system 参数 messages[{role: user, content: user_query}] ) model_response message.content[0].text try: # 解析模型返回的 JSON response_dict json.loads(model_response) action response_dict.get(action) if action calculate: expression response_dict[parameters][expression] result self._calculate(expression) if result is not None: # 将计算结果反馈给模型让它生成最终答案 follow_up_message f计算器返回的结果是{result}。请基于这个结果和原始问题生成对用户的最终回答。 final_message self.client.messages.create( modelself.model, max_tokens512, messages[ {role: user, content: user_query}, {role: assistant, content: model_response}, {role: user, content: follow_up_message} ] ) return final_message.content[0].text else: return 计算失败表达式可能无效或不安全。 elif action final_answer: return response_dict[final_answer] else: return 代理返回了无法识别的动作。 except json.JSONDecodeError: # 如果模型没有返回合法 JSON可能它直接给出了答案。 return model_response # 使用示例 if __name__ __main__: agent CalculatorAgent() questions [ 3 的 4 次方是多少, 一个半径为 5 的圆的面积是多少圆周率用 3.14 计算。, 你好今天天气怎么样 # 一个不需要计算的问题 ] for q in questions: print(f问题: {q}) answer agent.run(q) print(f回答: {answer}\n{-*50})这个示例展示了代理的核心思想模型决策代码执行。通过结构化提示词我们引导模型输出机器可读的指令从而将模型的推理能力与程序的执行能力结合起来。5. 生产环境关键考量与最佳实践将实验性的代理转化为稳定、可靠的生产服务需要关注以下方面。5.1 成本控制与速率限制API 调用是计费的并且有速率限制。不经控制的调用会导致高昂费用和服务中断。设置最大 Token 数始终明确设置max_tokens参数防止生成过长内容。实现重试机制使用指数退避策略处理速率限制错误。使用缓存对相同或相似的查询结果进行缓存避免重复调用。监控用量定期检查 API 使用量 dashboard并设置预算警报。# 一个带有简单重试和令牌限制的调用函数 import time from openai import RateLimitError def robust_api_call(api_func, *args, max_retries3, **kwargs): 一个带重试的稳健 API 调用函数。 for attempt in range(max_retries): try: response api_func(*args, **kwargs) return response except RateLimitError: wait_time 2 ** attempt # 指数退避 print(f达到速率限制第 {attempt1} 次重试等待 {wait_time} 秒...) time.sleep(wait_time) except Exception as e: print(fAPI 调用失败: {e}) break return None5.2 上下文长度管理与摘要模型有上下文窗口限制如 128K Token。长对话会耗尽上下文导致模型“忘记”最早的信息。摘要历史当对话历史过长时可以调用模型本身对之前的历史进行摘要然后用摘要代替冗长的原始历史。滑动窗口只保留最近 N 轮对话。重要信息优先识别并优先保留对话中的关键信息如用户偏好、任务目标。5.3 错误处理与用户体验代理不可能总是成功。健全的错误处理至关重要。API 错误妥善处理网络错误、认证失败、额度不足等情况给用户友好的提示。模型胡言乱语设置验证逻辑检查模型输出是否符合预期格式如 JSON 是否可解析。超时控制为 API 调用设置超时避免用户长时间等待。5.4 安全与合规输入过滤对用户输入进行必要的清理和过滤防止提示词注入攻击。输出审查对于生成的内容特别是面向公众的内容应有审查机制可以是另一个AI或规则。隐私保护避免在提示词中发送敏感用户数据如电话号码、邮箱。如需处理应进行脱敏。6. 常见问题排查在开发和部署 AI 代理时你会遇到一些典型问题。问题现象可能原因检查与解决方案API 调用返回认证错误API 密钥错误、未设置、或已失效。1. 检查.env文件是否存在且格式正确。2. 确认环境变量已加载 (print(os.getenv(‘KEY’)))。3. 在供应商平台检查密钥状态和额度。模型不遵循指令格式提示词不够清晰或温度 (temperature) 参数过高。1. 简化并强化系统提示词使用更明确的指令如“你必须以 JSON 格式回复”。2. 降低temperature值如从 0.8 降到 0.2使输出更确定。对话后期模型表现变差上下文窗口已满模型丢失了早期信息。1. 实现上下文管理策略摘要或滑动窗口。2. 监控对话的 Token 消耗。代理响应速度慢网络延迟、模型本身生成速度、或代码逻辑问题。1. 使用流式响应如果支持来提升感知速度。2. 检查是否有不必要的同步阻塞操作。3. 考虑使用更快的模型如 Claude Haiku。工具调用结果模型无法利用将工具结果反馈给模型的上下文不够清晰。1. 在反馈信息中明确说明这是工具的执行结果。2. 重新用完整的上下文原始问题模型决策工具结果提问。构建高效的 AI 代理是一个迭代过程。从最简单的单次调用开始逐步增加会话记忆、工具使用、复杂推理等能力并始终将稳定性、成本和安全性放在首位。通过本文介绍的模式和实践你可以根据具体业务需求打造出真正有用的智能体应用。
在实际 AI 开发和应用中直接调用大模型 API 往往只是第一步。真正让 AI 产生稳定、可控、可复用的价值需要将提示词Prompt与 AI 代理AI Agents结合起来构建能够理解复杂指令、执行多步任务、并具备一定自主决策能力的智能体。Claude 和 Codex 作为两类具有代表性的先进模型其代理模式的实践方式各有侧重。本文将围绕如何有效地配对提示词与 Claude/Codex AI 代理这一核心议题从概念理解、环境搭建、核心模式实现、到生产级最佳实践提供一个完整的工程指南。Claude 模型由 Anthropic 公司开发以其强大的对话能力、对指令的精准理解和良好的安全性设计著称。Codex 模型则由 OpenAI 推出是 GPT-3 的后代特别擅长理解和生成代码是 GitHub Copilot 的核心。所谓 AI 代理是指一个能够感知环境、进行决策并执行动作以达成目标的系统。当我们将精心设计的提示词注入这些强大的模型就能“激活”它们使其成为能够完成特定任务的代理。本文将带你完成从零构建一个基础 AI 代理的完整流程。你会学习到如何为 Claude 和 Codex 设计有效的提示词框架如何通过代码调用它们并处理响应以及如何构建一个能够进行多轮对话、具备工具使用能力或甚至能进行简单推理的代理系统。我们还将深入探讨在真实项目中最容易遇到的陷阱例如上下文管理、成本控制、错误处理等并提供具体的解决方案。1. 理解 AI 代理的核心提示词与模型的协同在深入代码之前必须清晰理解提示词Prompt与 AI 代理Agent之间的关系。这不是简单的“问与答”而更像是在为模型定义角色、任务、边界和交互规则。1.1 提示词作为代理的“操作手册”一个基础的提示词可能只是一个问题。但一个用于驱动代理的提示词则是一个复杂的规范。它通常包含以下几个部分系统角色设定明确告知模型它在当前会话中扮演的角色例如“你是一个专业的 Python 代码助手”或“你是一个能够分析用户需求并生成 SQL 查询的智能代理”。任务目标清晰、无歧义地描述需要完成的任务。步骤约束如果任务需要多步完成提示词可以规定步骤顺序或逻辑。输出格式要求指定模型返回数据的格式如 JSON、Markdown 或特定的代码结构。上下文规则说明如何利用之前的对话历史以及哪些信息是重要的。这种结构化的提示词将通用的语言模型“塑造”成了一个专用于特定任务的代理。1.2 Claude 与 Codex 代理的典型差异虽然核心思想一致但由于训练数据和设计目标的差异Claude 和 Codex 在构建代理时各有侧重。Claude 代理更擅长处理需要复杂逻辑推理、多轮对话、内容创作和安全合规的任务。它的强项在于理解模糊的人类指令并将其具体化。例如构建一个“产品需求分析代理”或“内容安全审核代理”Claude 是很好的选择。Codex 代理核心能力是代码生成、解释、补全和调试。因此Codex 代理天生适合构建“代码助手”、“自动化脚本生成器”、“SQL 查询生成器”或“代码审查工具”。它对编程语言的语法和语义有深刻的理解。理解这一差异是正确选型的第一步。一个需要与用户深入讨论需求再生成代码的场景可能更适合用 Claude 作为主代理在需要时调用 Codex 完成代码生成子任务。1.3 代理的基本工作流程一个典型的 AI 代理工作流程可以抽象为以下循环感知接收用户输入或环境信息。决策模型在提示词的引导下分析当前信息决定要执行的动作或要生成的内容。执行模型输出结果。在高级代理中这可能包括调用外部工具如 API、数据库。观察获取执行结果并将其作为新的上下文。循环重复步骤 2-4直到任务完成或达到终止条件。我们的目标就是用代码实现这个循环并将 Claude 或 Codex 模型作为决策的核心。2. 环境准备与 API 配置构建 AI 代理的第一步是准备好开发环境并获得模型 API 的访问权限。2.1 获取 API 密钥Claude API访问 Anthropic 官方开发者平台注册账号并申请 API 密钥。通常需要等待审核通过。Codex APICodex 模型通过 OpenAI API 提供。访问 OpenAI 平台注册账号并生成 API 密钥。请注意OpenAI API 是付费服务需要绑定支付方式。重要API 密钥是高度敏感信息绝不能直接硬编码在代码中或提交到版本控制系统如 Git。务必使用环境变量或安全的配置文件管理。2.2 Python 环境搭建我们将使用 Python 作为主要开发语言。确保你的环境满足以下要求Python 3.8 或更高版本。包管理工具pip。首先创建并激活一个虚拟环境这是一个良好的实践可以隔离项目依赖。# 创建虚拟环境 python -m venv ai_agent_venv # 激活虚拟环境 (Linux/macOS) source ai_agent_venv/bin/activate # 激活虚拟环境 (Windows PowerShell) .\ai_agent_venv\Scripts\Activate.ps12.3 安装必要的库根据你选择的模型安装对应的官方 SDK 或其他辅助库。# 如果你主要使用 Claude pip install anthropic # 如果你主要使用 OpenAI (Codex) pip install openai # 通用工具库用于处理环境变量和 JSON pip install python-dotenv requests2.4 配置 API 密钥创建一个名为.env的文件在你的项目根目录下用于存储环境变量。# .env 文件内容 ANTHROPIC_API_KEYyour_anthropic_api_key_here OPENAI_API_KEYyour_openai_api_key_here然后在 Python 代码中安全地加载这些密钥。# config.py import os from dotenv import load_dotenv load_dotenv() # 加载 .env 文件中的环境变量 ANTHROPIC_API_KEY os.getenv(ANTHROPIC_API_KEY) OPENAI_API_KEY os.getenv(OPENAI_API_KEY) # 检查密钥是否成功加载 if not ANTHROPIC_API_KEY: print(警告: 未找到 ANTHROPIC_API_KEY) if not OPENAI_API_KEY: print(警告: 未找到 OPENAI_API_KEY)3. 构建基础代理从单次调用到会话管理现在我们开始编写代码实现最基本的代理交互并逐步增加会话管理能力。3.1 实现一个简单的 Claude 代理以下代码展示了一个最简单的 Claude 代理它接收一个提示词返回模型生成的文本。# claude_agent_simple.py import anthropic from config import ANTHROPIC_API_KEY def simple_claude_agent(prompt: str, model: str claude-3-sonnet-20240229) - str: 一个简单的 Claude 代理函数。 Args: prompt: 发送给 Claude 的完整提示词。 model: 使用的 Claude 模型版本。 Returns: Claude 模型生成的文本内容。 client anthropic.Anthropic(api_keyANTHROPIC_API_KEY) message client.messages.create( modelmodel, max_tokens1024, messages[ { role: user, content: prompt } ] ) # 提取并返回模型的回复内容 return message.content[0].text # 使用示例 if __name__ __main__: user_query 请用 Python 写一个函数计算斐波那契数列的第 n 项。 response simple_claude_agent(user_query) print(Claude 的回答) print(response)3.2 实现一个简单的 Codex 代理Codex 代理的调用方式与 Claude 类似但通过 OpenAI 的 API。以下示例使用gpt-3.5-turbo-instructCodex 的替代品OpenAI 已推荐使用此模型进行代码补全任务。# codex_agent_simple.py import openai from config import OPENAI_API_KEY def simple_codex_agent(prompt: str, model: str gpt-3.5-turbo-instruct) - str: 一个简单的 Codex 风格代理函数用于代码生成。 Args: prompt: 代码生成指令。 model: 使用的模型。 Returns: 模型生成的代码。 openai.api_key OPENAI_API_KEY response openai.Completions.create( modelmodel, promptprompt, max_tokens500, temperature0.2 # 温度值较低生成结果更确定适合代码 ) return response.choices[0].text.strip() # 使用示例 if __name__ __main__: code_prompt # 根据以下要求编写一个 Python 函数 # 1. 函数名为 validate_email # 2. 接收一个字符串参数 email # 3. 使用正则表达式验证该字符串是否为有效的电子邮件格式 # 4. 返回布尔值True 表示有效False 表示无效 import re def validate_email(email): generated_code simple_codex_agent(code_prompt) print(生成的代码) print(generated_code)3.3 为代理添加会话记忆多轮对话单次调用的代理能力有限。真正的代理需要记住对话历史实现连贯的多轮交互。下面的ConversationalAgent类实现了基本的会话记忆功能。# conversational_agent.py import anthropic from typing import List, Dict from config import ANTHROPIC_API_KEY class ConversationalAgent: 一个具备会话记忆能力的 AI 代理基类。 def __init__(self, system_prompt: str, model: str claude-3-sonnet-20240229): 初始化代理。 Args: system_prompt: 定义代理角色和能力的系统提示词。 model: 使用的模型名称。 self.client anthropic.Anthropic(api_keyANTHROPIC_API_KEY) self.model model self.conversation_history: List[Dict] [] # 将系统提示词作为第一条消息加入历史 if system_prompt: self.conversation_history.append({role: user, content: system_prompt}) # 这里可以添加一条模拟的助理回复或者等待第一次用户输入后再获取回复。 # 更常见的做法是将系统提示词放在每次请求的“系统”角色消息中但Anthropic Messages API 使用方式略有不同。 # 我们采用另一种方式将系统提示词与用户消息组合。 def _build_messages(self, user_input: str) - List[Dict]: 构建发送给 API 的消息列表。 # 对于 Claude我们可以将系统提示词与用户输入结合或者使用专门的系统消息如果API支持。 # 这里我们采用一种简单方法将系统提示词作为历史的一部分。 # 在实际最新API中可以使用 system 参数。 messages self.conversation_history.copy() messages.append({role: user, content: user_input}) return messages def get_response(self, user_input: str) - str: 处理用户输入并返回代理的回复。 messages_for_api self._build_messages(user_input) try: message self.client.messages.create( modelself.model, max_tokens1024, messagesmessages_for_api ) assistant_reply message.content[0].text # 更新对话历史 self.conversation_history.append({role: user, content: user_input}) self.conversation_history.append({role: assistant, content: assistant_reply}) return assistant_reply except Exception as e: return f抱歉代理在处理您的请求时出现了错误{str(e)} def clear_history(self): 清空对话历史。 self.conversation_history.clear() # 使用示例创建一个代码助手代理 if __name__ __main__: system_prompt 你是一个专业的Python代码助手。你的职责是 1. 根据用户需求生成准确、高效的Python代码。 2. 解释代码的逻辑和关键部分。 3. 如果用户代码有错误帮助诊断并提出修改建议。 请用中文与用户交流。 code_agent ConversationalAgent(system_promptsystem_prompt) print(代码助手代理已启动。输入退出来结束对话。) while True: user_input input(\n您: ) if user_input.lower() in [退出, exit, quit]: break response code_agent.get_response(user_input) print(f\n助手: {response})这个代理现在可以记住整个对话上下文用户可以进行如“帮我写一个函数” - “现在为这个函数添加注释” - “如果输入不是数字怎么办”这样的连贯对话。4. 高级模式工具使用与推理代理基础代理只能生成文本。高级代理常被称为“智能体”或“Agents”能够理解何时需要以及如何使用外部工具如计算器、搜索引擎、数据库来完成任务。这通常通过让模型生成结构化的响应如 JSON来实现然后代码解析这个响应并执行相应动作。4.1 设计工具使用的工作流程其核心工作流程如下用户输入代理接收用户查询。模型思考模型分析查询判断是否需要使用工具、使用哪个工具、以及需要什么参数。生成结构化请求模型输出一个预定义格式的请求例如{action: search_web, parameters: {query: Python latest features}}。代码执行工具代理的代码解析这个请求调用相应的工具函数如调用 Google Search API。获取工具结果工具返回结果如搜索到的网页摘要。模型合成答案将工具结果作为新上下文再次发送给模型让模型合成最终答案回复给用户。4.2 实现一个具备计算能力的代理下面是一个简化版的工具使用代理示例它让 Claude 能够使用一个计算器工具。# tool_using_agent.py import anthropic import json import re from config import ANTHROPIC_API_KEY class CalculatorAgent: 一个可以使用计算器工具的 AI 代理。 def __init__(self): self.client anthropic.Anthropic(api_keyANTHROPIC_API_KEY) self.model claude-3-sonnet-20240229 def _calculate(self, expression: str) - float: 一个安全的计算器函数。注意在生产环境中使用 eval 是危险的这里仅作演示。 # 严重警告在实际生产环境中直接使用 eval 处理用户输入是极其危险的可能导致代码执行漏洞。 # 这里为了演示进行了极简单的过滤。真实场景应使用 AST 解析或专门的数学表达式库如 numexpr。 # 只允许数字、基本运算符和括号 if re.match(r^[\d\\-\*\/\(\)\.\s]$, expression): try: return eval(expression) except: return None else: return None def run(self, user_query: str) - str: 运行代理处理用户查询。 # 系统提示词明确告诉模型可以使用工具以及格式。 system_prompt 你是一个智能助手可以回答问题和进行数学计算。 当你遇到需要计算数学表达式的问题时你可以使用计算器工具。 为了使用工具请严格按照以下 JSON 格式回复 { thoughts: 你的思考过程解释为什么需要计算, action: calculate, // 或者 final_answer parameters: { expression: 待计算的数学表达式例如 2 3 * (10 - 4) // 当 action 为 calculate 时需要 }, final_answer: 直接给用户的最终答案 // 当 action 为 final_answer 时需要 } 请只输出这个 JSON 对象不要有其他任何文字。 # 构建消息 message self.client.messages.create( modelself.model, max_tokens1024, systemsystem_prompt, # 使用 system 参数 messages[{role: user, content: user_query}] ) model_response message.content[0].text try: # 解析模型返回的 JSON response_dict json.loads(model_response) action response_dict.get(action) if action calculate: expression response_dict[parameters][expression] result self._calculate(expression) if result is not None: # 将计算结果反馈给模型让它生成最终答案 follow_up_message f计算器返回的结果是{result}。请基于这个结果和原始问题生成对用户的最终回答。 final_message self.client.messages.create( modelself.model, max_tokens512, messages[ {role: user, content: user_query}, {role: assistant, content: model_response}, {role: user, content: follow_up_message} ] ) return final_message.content[0].text else: return 计算失败表达式可能无效或不安全。 elif action final_answer: return response_dict[final_answer] else: return 代理返回了无法识别的动作。 except json.JSONDecodeError: # 如果模型没有返回合法 JSON可能它直接给出了答案。 return model_response # 使用示例 if __name__ __main__: agent CalculatorAgent() questions [ 3 的 4 次方是多少, 一个半径为 5 的圆的面积是多少圆周率用 3.14 计算。, 你好今天天气怎么样 # 一个不需要计算的问题 ] for q in questions: print(f问题: {q}) answer agent.run(q) print(f回答: {answer}\n{-*50})这个示例展示了代理的核心思想模型决策代码执行。通过结构化提示词我们引导模型输出机器可读的指令从而将模型的推理能力与程序的执行能力结合起来。5. 生产环境关键考量与最佳实践将实验性的代理转化为稳定、可靠的生产服务需要关注以下方面。5.1 成本控制与速率限制API 调用是计费的并且有速率限制。不经控制的调用会导致高昂费用和服务中断。设置最大 Token 数始终明确设置max_tokens参数防止生成过长内容。实现重试机制使用指数退避策略处理速率限制错误。使用缓存对相同或相似的查询结果进行缓存避免重复调用。监控用量定期检查 API 使用量 dashboard并设置预算警报。# 一个带有简单重试和令牌限制的调用函数 import time from openai import RateLimitError def robust_api_call(api_func, *args, max_retries3, **kwargs): 一个带重试的稳健 API 调用函数。 for attempt in range(max_retries): try: response api_func(*args, **kwargs) return response except RateLimitError: wait_time 2 ** attempt # 指数退避 print(f达到速率限制第 {attempt1} 次重试等待 {wait_time} 秒...) time.sleep(wait_time) except Exception as e: print(fAPI 调用失败: {e}) break return None5.2 上下文长度管理与摘要模型有上下文窗口限制如 128K Token。长对话会耗尽上下文导致模型“忘记”最早的信息。摘要历史当对话历史过长时可以调用模型本身对之前的历史进行摘要然后用摘要代替冗长的原始历史。滑动窗口只保留最近 N 轮对话。重要信息优先识别并优先保留对话中的关键信息如用户偏好、任务目标。5.3 错误处理与用户体验代理不可能总是成功。健全的错误处理至关重要。API 错误妥善处理网络错误、认证失败、额度不足等情况给用户友好的提示。模型胡言乱语设置验证逻辑检查模型输出是否符合预期格式如 JSON 是否可解析。超时控制为 API 调用设置超时避免用户长时间等待。5.4 安全与合规输入过滤对用户输入进行必要的清理和过滤防止提示词注入攻击。输出审查对于生成的内容特别是面向公众的内容应有审查机制可以是另一个AI或规则。隐私保护避免在提示词中发送敏感用户数据如电话号码、邮箱。如需处理应进行脱敏。6. 常见问题排查在开发和部署 AI 代理时你会遇到一些典型问题。问题现象可能原因检查与解决方案API 调用返回认证错误API 密钥错误、未设置、或已失效。1. 检查.env文件是否存在且格式正确。2. 确认环境变量已加载 (print(os.getenv(‘KEY’)))。3. 在供应商平台检查密钥状态和额度。模型不遵循指令格式提示词不够清晰或温度 (temperature) 参数过高。1. 简化并强化系统提示词使用更明确的指令如“你必须以 JSON 格式回复”。2. 降低temperature值如从 0.8 降到 0.2使输出更确定。对话后期模型表现变差上下文窗口已满模型丢失了早期信息。1. 实现上下文管理策略摘要或滑动窗口。2. 监控对话的 Token 消耗。代理响应速度慢网络延迟、模型本身生成速度、或代码逻辑问题。1. 使用流式响应如果支持来提升感知速度。2. 检查是否有不必要的同步阻塞操作。3. 考虑使用更快的模型如 Claude Haiku。工具调用结果模型无法利用将工具结果反馈给模型的上下文不够清晰。1. 在反馈信息中明确说明这是工具的执行结果。2. 重新用完整的上下文原始问题模型决策工具结果提问。构建高效的 AI 代理是一个迭代过程。从最简单的单次调用开始逐步增加会话记忆、工具使用、复杂推理等能力并始终将稳定性、成本和安全性放在首位。通过本文介绍的模式和实践你可以根据具体业务需求打造出真正有用的智能体应用。
)
