基于Claude与Codex的多模型协作AI Agent搭建指南

在实际 AI 编程和自动化工作流构建中开发者常常面临一个选择是依赖一个全能但可能在某些领域不够精深的通用大模型还是组合多个各有所长的专用模型来协同工作后者通常能带来更高的代码质量、更精准的上下文理解和更稳定的输出。Claude Code 和 Codex 作为两个在代码生成与理解领域备受关注的工具如果能让它们为另一个强大的模型比如 Hermes充当“工具人”形成一个智能体Agent协作体系无疑能极大提升开发效率。本文将带你从零开始理解这种协作模式的核心思想并完成一个可运行的、由 Claude Code 和 Codex 辅助 Hermes 模型进行代码任务的本地 Agent 环境搭建与验证。这种模式的核心价值在于“专长分工”。Claude 系列模型以强大的逻辑推理和长上下文处理能力著称Codex或其背后的模型则在代码补全和语法理解上表现出色而 Hermes 模型可能专注于特定领域的任务规划或决策。让它们协同工作意味着你可以用 Hermes 作为“大脑”进行任务分解和决策调用 Claude Code 进行复杂逻辑的代码块生成或审查再让 Codex 处理琐碎的语法补全和代码片段填充。这比单独使用任何一个模型都更接近一个资深开发者的思考和工作流程。1. 理解核心概念Agent、工具人与模型协作在开始动手之前需要明确几个关键概念这决定了我们后续搭建环境时的技术选型和架构设计。1.1 什么是 AI AgentAI Agent智能体在此语境下指的是一个能够感知环境、进行决策并执行动作以达成目标的程序化实体。在我们的场景中这个“环境”是你的代码库、终端命令或API接口“决策”由核心模型如 Hermes做出“动作”则可能包括调用 Claude Code 生成代码、调用 Codex 补全代码、执行脚本、读写文件等。Agent 框架负责管理这些模型的调用顺序、上下文传递和错误处理。1.2 “工具人”模式如何工作“工具人”是一种形象的比喻指代那些被核心 Agent 调用的、功能相对单一且专业的服务或模型。在这种架构中Hermes核心 Agent担任指挥官角色。它接收用户的高层任务如“构建一个用户登录API”将其分解为子任务设计数据库表、编写控制器、实现服务层、编写单元测试。Claude Code高级工具人担任架构师或高级工程师角色。当 Hermes 判断某个子任务需要复杂的逻辑设计、算法实现或代码审查时它会将需求附带必要的上下文提交给 Claude Code并获取生成的代码块。Codex基础工具人担任熟练工角色。当任务涉及标准的代码补全、简单的函数填充、或根据现有代码模式进行扩展时Hermes 会调用 Codex 来快速完成这些工作。这种分工协作的关键在于“路由逻辑”——即 Hermes 如何根据任务类型决定调用哪个工具。这通常需要预先定义一套规则或训练一个轻量级的分类器。1.3 相关技术栈辨析为了避免混淆我们需要厘清搜索热词中一些容易混淆的术语Claude Code通常指 Claude 模型在代码编辑环境如 Cursor、VS Code 插件中的集成应用它提供了针对编程优化的交互界面和指令。在 Agent 上下文中我们更关注其背后的 Claude API 的代码生成能力。CodexOpenAI 发布的专注于代码生成的模型系列是 GitHub Copilot 的早期基础。现在通常泛指具有强大代码补全能力的模型或 API。Hermes这里可能指 Hermes-2 等开源模型也可能是某个特定任务优化的模型代号。在本文中我们将其视为一个可接收指令、进行任务规划并调用其他工具的核心决策模型。Agent 框架如 LangChain、LlamaIndex、AutoGen 等它们提供了构建多模型协作流程的基础设施。我们将选择其中一个进行演示。2. 环境准备与依赖配置我们将使用 Python 作为粘合剂利用 LangChain 框架来构建这个多模型 Agent 系统。LangChain 的优势在于其丰富的工具集成和清晰的 Agent 执行流程。2.1 基础环境要求确保你的开发环境满足以下条件组件要求说明操作系统Windows 10/11, macOS, Linux (推荐)需支持 Python 运行。Python3.8 - 3.113.12 可能存在部分库的兼容性问题建议使用 3.10。包管理工具pip (21.0)用于安装 Python 依赖。代码编辑器VS Code (推荐)便于管理和运行 Python 脚本。API 密钥Anthropic (Claude)、OpenAI (或兼容 Codex 的 API)访问对应模型服务的凭证。核心决策模型Hermes可以使用 OpenAI 的 GPT-4 或开源模型本地部署来模拟。注意本文以使用云端 APIClaude、OpenAI为例进行演示因为这是最快速的上手方式。如果你想完全本地化运行需要准备足够显存的 GPU 来部署类似 Hermes 的开源模型如NousResearch/Hermes-2-Pro-Llama-3-8B并使用ollama或vLLM等工具提供本地 API。2.2 创建项目与安装依赖首先创建一个干净的项目目录并初始化虚拟环境这能有效隔离依赖。# 创建项目目录并进入 mkdir ai-code-agent cd ai-code-agent # 创建虚拟环境 (以 Linux/macOS 为例Windows 下使用 python -m venv venv) python3 -m venv venv # 激活虚拟环境 # Linux/macOS: source venv/bin/activate # Windows: # venv\Scripts\activate # 升级 pip pip install --upgrade pip接下来安装核心的 LangChain 库以及连接 Claude、OpenAI API 所需的库。我们还会安装python-dotenv来管理环境变量中的 API 密钥。pip install langchain langchain-anthropic langchain-openai python-dotenvlangchain: Agent 框架核心。langchain-anthropic: LangChain 官方维护的 Claude API 集成。langchain-openai: LangChain 官方维护的 OpenAI API 集成可用于访问 GPT 系列或 Codex 风格的模型。python-dotenv: 从.env文件加载环境变量。2.3 配置 API 密钥与环境变量永远不要将 API 密钥硬编码在代码中。我们将使用.env文件来安全地存储它们。在项目根目录下创建一个名为.env的文件并填入你的密钥# .env 文件 ANTHROPIC_API_KEYyour_anthropic_api_key_here OPENAI_API_KEYyour_openai_api_key_here # 如果你使用其他兼容 OpenAI 的本地模型服务可以这样配置 # OPENAI_API_BASEhttp://localhost:11434/v1 # 例如 ollama 的地址然后在代码中通过os.getenv或dotenv来读取这些变量。3. 构建基础的多工具 Agent 系统现在我们将开始编写代码创建一个能够同时调用 Claude 和 OpenAI (模拟 Codex) 的简单 Agent。3.1 初始化模型客户端首先创建一个main.py文件并初始化与 Claude 和 OpenAI 服务的连接。# main.py import os from dotenv import load_dotenv from langchain_anthropic import ChatAnthropic from langchain_openai import ChatOpenAI # 加载 .env 文件中的环境变量 load_dotenv() # 初始化 Claude 客户端 (作为“高级工具人”) # 使用 Claude 3 系列模型例如 claude-3-haiku-20240307它速度快、成本低适合作为工具 claude_llm ChatAnthropic( modelclaude-3-haiku-20240307, temperature0.1, # 低 temperature 使输出更确定适合代码生成 api_keyos.getenv(ANTHROPIC_API_KEY) ) # 初始化 OpenAI 客户端 (作为“基础工具人”和“核心决策者”) # 使用 gpt-4 或 gpt-3.5-turbo 作为核心决策模型模拟 Hermes 的角色 hermes_llm ChatOpenAI( modelgpt-4-turbo, # 或 gpt-3.5-turbo temperature0.3, # 稍高的创造性用于任务规划和决策 api_keyos.getenv(OPENAI_API_KEY), # 如果使用本地模型请设置 base_url # base_urlos.getenv(OPENAI_API_BASE) ) # 再初始化一个专门用于代码补全的 OpenAI 模型 (模拟 Codex) # 注意OpenAI 已不再单独提供 Codex API但 gpt-3.5-turbo-instruct 或 gpt-4 在代码任务上表现类似 codex_llm ChatOpenAI( modelgpt-3.5-turbo-instruct, # 这个模型更适合指令跟随和补全 temperature0.1, api_keyos.getenv(OPENAI_API_KEY), max_tokens500 # 限制单次补全的长度 ) print(模型客户端初始化成功)3.2 为工具人定义“工具”在 LangChain 中“工具”是一个可调用的函数它封装了特定的能力。我们将为 Claude 和 Codex 分别创建工具。# 继续在 main.py 中编写 from langchain.agents import Tool from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser # 1. 定义 Claude 工具用于复杂代码生成和逻辑设计 def call_claude_for_complex_code(task_description: str, context: str ) - str: 调用 Claude 生成复杂逻辑的代码。 prompt ChatPromptTemplate.from_messages([ (system, 你是一个资深软件工程师擅长编写清晰、健壮、可维护的代码。请根据用户需求生成完整的代码片段。), (user, f任务描述{task_description}\n\n相关上下文{context}\n\n请直接输出代码无需解释。) ]) chain prompt | claude_llm | StrOutputParser() return chain.invoke({}) # 2. 定义 Codex 工具用于简单代码补全和片段生成 def call_codex_for_completion(partial_code: str, language: str python) - str: 调用 Codex 风格模型补全代码。 prompt ChatPromptTemplate.from_messages([ (system, f你是一个{language}代码补全专家。只补全代码不要添加任何额外解释。), (user, f请补全以下代码\n{language}\n{partial_code}\n) ]) chain prompt | codex_llm | StrOutputParser() result chain.invoke({}) # 清理可能出现的 markdown 代码块标记 if result.startswith(): lines result.split(\n) result \n.join(lines[1:-1]) if lines[-1].startswith() else \n.join(lines[1:]) return result # 3. 将函数包装成 LangChain Tool 对象 tools [ Tool( nameClaudeCodeGenerator, funccall_claude_for_complex_code, description在需要生成涉及复杂业务逻辑、算法、类设计、API接口或需要深度推理的代码时使用此工具。 输入应该是一个清晰的任务描述可以可选地包含一些上下文代码。 ), Tool( nameCodexCodeCompleter, funccall_codex_for_completion, description在需要补全现有代码行、编写简单的工具函数、填充模板代码或进行语法级补全时使用此工具。 输入应该是一段不完整的代码片段并指定编程语言。 ) ] print(f已定义 {len(tools)} 个工具。)3.3 创建核心 Agent 并定义路由逻辑我们将使用 LangChain 的create_react_agent来创建一个能够使用上述工具的 Agent。ReAct 框架让 Agent 能够进行“思考-行动-观察”的循环。# 继续在 main.py 中编写 from langchain.agents import create_react_agent, AgentExecutor from langchain import hub # 从 LangChain Hub 拉取一个适合的 ReAct 提示词模板 # 你也可以自定义这个模板以更好地指导 Hermes 如何选择工具 prompt hub.pull(hwchase17/react) # 使用我们模拟 Hermes 的 LLM 和定义的工具创建 Agent agent create_react_agent(llmhermes_llm, toolstools, promptprompt) # 创建 Agent 执行器它负责运行循环 agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 设置为 True 可以看到 Agent 的思考过程便于调试 handle_parsing_errorsTrue # 处理解析错误 ) print(Agent 执行器创建成功)4. 运行验证与结果分析现在让我们用一个具体的编程任务来测试这个多模型协作的 Agent。4.1 设计测试任务我们设计一个需要分步骤完成的任务以观察 Agent 如何分配工作任务“请帮我创建一个 Python 函数用于从给定的 URL 下载图片并将其缩放到指定宽度同时保持宽高比。最后将处理后的图片保存到本地。”这个任务可以分解为复杂逻辑部分设计主函数框架、错误处理、下载逻辑、图片处理逻辑。这适合交给 Claude。简单补全部分可能需要补全一些导入语句如import requests、简单的文件操作代码。这适合交给 Codex。4.2 执行任务并观察过程在main.py末尾添加执行代码# 继续在 main.py 中编写 if __name__ __main__: test_task 请帮我创建一个 Python 函数名为 download_and_resize_image。 函数参数url (图片URL), save_path (保存路径), target_width (目标宽度整数)。 函数功能从 url 下载图片将其宽度缩放到 target_width 像素高度按原图宽高比自动计算然后将处理后的图片保存到 save_path。 要求包含必要的错误处理如下载失败、非图片文件、处理错误等并使用常见的库如 requests, Pillow。 print(*50) print(开始执行任务...) print(f任务描述{test_task}) print(*50) try: result agent_executor.invoke({input: test_task}) print(\n *50) print(任务执行完成) print(*50) print(最终输出\n, result[output]) except Exception as e: print(f执行过程中出现错误{e})运行脚本python main.py当verboseTrue时你将在控制台看到类似以下的详细思考过程此为示例实际输出可能不同开始执行任务... 任务描述... Thought: 用户需要创建一个功能完整的图片处理函数。这涉及到网络请求、图片处理和文件IO逻辑较为复杂。我应该先使用 ClaudeCodeGenerator 来生成函数的主体框架和核心逻辑。 Action: ClaudeCodeGenerator Action Input: 创建一个Python函数 download_and_resize_image参数为 url, save_path, target_width。功能是下载图片用Pillow库按给定宽度等比例缩放并保存。需要包含requests下载错误、PIL处理错误、文件保存错误的异常处理。 Observation: [Claude 生成的代码包含函数定义、try-catch块、requests.get、Image.open、resize、save等] Thought: Claude 生成了很好的主体代码。但我注意到它使用了 from PIL import Image而 requests 的导入也包含了。为了代码更完整我可以让 CodexCodeCompleter 检查一下导入部分或者补全一个使用示例。 Action: CodexCodeCompleter Action Input: from PIL import Image\nimport requests\n\n [后面接上 Claude 生成的函数定义] 请为这个函数添加一个简单的 if __name__ __main__: 使用示例。 Observation: [Codex 补全的示例代码例如调用函数并打印结果] Thought: 我已经有了完整的函数和示例。现在可以将最终结果返回给用户。 Action: Final Answer Final Answer: 以下是完整的代码实现...[整合后的代码]4.3 分析输出结果成功的运行将输出一个完整的 Python 脚本。你应该检查这个脚本是否函数签名正确。包含了requests和PILPillow的导入。实现了下载带超时和状态码检查、图片打开、尺寸计算、缩放和保存的逻辑。使用了try...except块来捕获requests.exceptions.RequestException,IOError,PIL.UnidentifiedImageError等异常。包含了一个可运行的示例。这个输出验证了你的 Agent 系统能够理解复杂任务并成功地将子任务路由给合适的“工具人”模型去执行最后整合结果。5. 常见问题排查在搭建和运行过程中你可能会遇到以下问题5.1 API 连接与认证失败问题现象可能原因检查与解决AuthenticationError或Invalid API Key1..env文件未加载或路径错误。2. API 密钥未正确设置或已失效。3. 环境变量名在代码中拼写错误。1. 确认load_dotenv()被调用且.env文件与脚本在同一目录或指定了正确路径。2. 前往 Anthropic/OpenAI 控制台检查密钥状态并重新复制。3. 在代码中print(os.getenv(‘ANTHROPIC_API_KEY’)[:5])检查是否能打印出部分密钥勿打印全部。ConnectionError或超时1. 网络问题。2. 如果使用本地模型base_url配置错误或服务未启动。1. 检查网络连接尝试curlAPI 端点。2. 对于本地模型确认服务如 ollama正在运行且base_url指向正确的http://host:port/v1。5.2 模型调用与响应异常问题现象可能原因检查与解决ModelNotFoundError(如claude-3-haiku-20240307)1. 模型名称拼写错误。2. 该模型在对应 API 中不可用或已过时。1. 查阅官方文档使用正确的模型标识符。例如 Anthropic 的模型列表会更新。2. 尝试使用更通用的模型名如claude-3-haiku-latest。生成的代码不完整或不符合预期1.temperature参数过高导致输出随机。2. 提示词Prompt不够清晰具体。3. 工具的描述 (description) 不够准确导致 Agent 路由错误。1. 将temperature调低如 0.1-0.3。2. 优化工具函数内的prompt和 Agent 使用的react提示词模板给出更明确的指令和格式要求。3. 仔细打磨工具的description明确其适用场景和输入格式。Agent 陷入循环或调用错误工具1. Agent 的max_iterations可能设置过高或未设置限制。2. 工具描述模糊导致 Agent 无法区分。1. 在AgentExecutor中设置max_iterations10和max_execution_time60来限制执行。2. 清晰区分工具职责Claude 负责“复杂、完整、设计”Codex 负责“补全、简单、片段”。5.3 本地模型部署问题如果你选择本地部署 Hermes 等模型可能会遇到问题现象可能原因检查与解决本地服务启动失败1. 显存不足。2. 模型文件未正确下载。3. 端口被占用。1. 选择参数量更小的模型如 7B。2. 使用ollama pull或确认模型文件路径。3. 更换服务端口。LangChain 无法连接本地 API1.base_url格式错误。2. 本地 API 服务未兼容 OpenAI 格式。1. 确保base_url以/v1结尾例如http://localhost:11434/v1。2. 使用curl测试本地 API 端点是否返回 OpenAI 兼容的响应格式。许多本地服务工具如 ollama, LM Studio都提供兼容模式。6. 最佳实践与扩展方向一个基础的多模型协作 Agent 已经搭建完成但要将其用于更严肃的项目或生产环境还需要考虑以下几点。6.1 生产环境考量错误处理与重试为每个工具调用添加重试逻辑和更细致的异常捕获。网络请求和远程 API 调用是不稳定的。from tenacity import retry, stop_after_attempt, wait_exponential retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min4, max10)) def call_claude_with_retry(task_description: str): # ... 原有逻辑成本与速率限制管理监控 API 调用次数和 Token 消耗。为不同的工具设置不同的速率限制避免短时间内请求过多导致失败或产生高额费用。上下文管理目前的简单示例中每次工具调用都是独立的。复杂的任务可能需要 Agent 在多次工具调用间维护一个共享的上下文如已生成的代码片段、用户反馈。这需要更高级的 Agent 架构如使用ConversationBufferMemory。结果验证不要盲目信任 AI 生成的代码。引入一个验证步骤例如对生成的 Python 代码运行ast.parse()检查语法或在一个安全的沙箱环境中执行简单的单元测试。配置外置将模型名称、temperature、API base URL 等配置移出代码放入配置文件如config.yaml或环境变量中。6.2 扩展更多“工具人”当前的系统只有两个工具。你可以轻松地扩展它代码审查工具添加一个调用 GPT-4 或 Claude Sonnet 来审查生成代码安全性、性能和可读性的工具。Shell 执行工具让 Agent 能够执行pip install或运行测试脚本实现真正的自动化。警告此操作极其危险必须严格限制命令白名单和沙箱环境文档查询工具集成一个向量数据库让 Agent 可以查询内部技术文档或 API 手册。专有模型工具为特定任务如 SQL 生成、UI 代码生成集成更专业的模型。6.3 优化路由逻辑目前的路由完全依赖 LangChain 的 ReAct Agent 和工具描述。对于更复杂的场景你可以自定义 Agent 提示词修改从 Hub 拉取的react提示词加入更多关于如何选择工具的示例few-shot learning。使用更高级的 Agent 类型尝试OPENAI_FUNCTIONS或STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION类型的 Agent它们可能对工具选择有更好的支持。实现分层路由先用一个轻量级分类器甚至是一套规则判断任务类型再决定调用哪个工具链而不是完全依赖大模型自己决定。6.4 从模拟到真实的 Hermes本文用 GPT-4 模拟了 Hermes 的决策角色。如果你想使用真正的 Hermes 开源模型使用ollama拉取并运行 Hermes 模型ollama run hermes2-pro。确保 ollama 服务运行在http://localhost:11434并提供了 OpenAI 兼容的 API 端点 (/v1)。将hermes_llm的初始化改为指向本地服务hermes_llm ChatOpenAI( modelhermes2-pro, # ollama 中的模型名 base_urlhttp://localhost:11434/v1, api_keyollama, # ollama 通常不需要真正的 key但 LangChain 要求非空 temperature0.3, )注意本地模型的推理速度和上下文长度可能与云端 API 有差异需要调整超时设置和任务复杂度。通过以上步骤你不仅搭建了一个可用的多模型编程助手原型更掌握了一套构建专用 AI 协作系统的核心方法。关键在于理解每个组件的职责设计清晰的交互协议并始终将人的审查和把控作为最终环节。