,CodeAct技术原理从入门到精通,收藏这一篇就够了!)
当 Function Calling 局限于预定义工具、ReAct 受困于文本格式解析时一种更激进的 Agent 方案浮出水面——让大模型直接生成并执行代码来解决问题。本文将深入剖析 CodeAct 的设计理念、架构实现与工程实践。一、从调用工具到编写代码Agent 行动范式的演进在 AI Agent 的发展脉络中“行动”Action的定义经历了三次跃迁范式行动方式灵活度代表方案Function Calling调用预定义的函数低——受限于已注册的工具集OpenAI tools APIReAct文本指令选择工具中——可灵活推理但仍依赖预定义工具Thought-Action 循环CodeAct生成并执行任意代码高——Python 能做的它都能做代码即行动Function Calling 和 ReAct 的共同局限是模型只能从有限的工具菜单中点菜。如果用户的问题超出了预定义工具的覆盖范围模型就无能为力。CodeAct 的核心洞察是Python 代码本身就是最通用的工具。与其为每种需求预定义一个函数不如让模型直接编写代码来解决问题。一段 Python 代码可以做计算、处理数据、调用 API、操作文件——它的能力上限就是编程语言本身。二、架构总览基于 LangGraph 的状态机设计CodeAct 的实现采用了 LangGraph 的状态图StateGraph架构整体流程可以概括为用户提问 → LLM 生成代码 → 执行代码 → 将结果反馈给 LLM → LLM 判断是否满足是 → 输出答案 / 否 → 修改代码再次执行用一张图表示状态流转┌──────────────────────────────────┐ │ │ ▼ │ START → [llm_call] → [enter_process] │ │ │ │ 有代码输出 无代码输出 │ │ │ │ ▼ END │ [process_node] ─────────────┘ (执行代码)这是一个典型的自我纠错循环模型生成代码、执行、观察结果如果不满意则修改代码重试直到产出最终答案。三、核心组件逐一拆解3.1 状态定义对话、行动、输出三位一体class OverallState(TypedDict): messages: Annotated[list, add_messages] # 对话历史 actions: list[dict] # 待执行的代码动作 output: str # 最终输出 user_prompt: str # 用户原始问题这个状态设计有几个值得注意的点messages使用 LangGraph 的add_messages注解支持消息的自动追加与合并天然适配多轮对话。actions存储从 LLM 回复中解析出的代码块格式为{tool: execute_python, tool_input: code}。output作为终止信号——当它非空时表示 LLM 已生成最终答案循环结束。3.2 System Prompt定义代码助手的行为规范SYSTEM_PROMPT 你是一个能够编写和执行代码的智能助手。 当用户提出问题时你需要 1. 分析问题并确定需要编写什么代码 2. 编写能解决问题的Python代码 3. 使用execute_python工具执行代码 4. 分析执行结果如果有错误则修改代码再次执行 5. 最终给用户提供答案 请确保你的代码能够正确执行并将最终结果存储在名为result的变量中。这段 Prompt 虽然简短却建立了三个关键契约代码优先引导模型面对问题时首先想到编写代码而非直接文本回答。自我修复明确告诉模型如果有错误则修改代码再次执行赋予了自我纠错的行为模式。结果约定要求将最终结果存入result变量为代码执行后的结果提取提供了统一入口。3.3 LLM 调用节点代码提取的关键逻辑def _create_agent_action(ai_message): content ai_message.content if python in content: code_blocks content.split(python) code code_blocks[1].split()[0].strip() return {tool: execute_python, tool_input: code} return None def llm_call(state: OverallState): messages [ SystemMessage(contentSYSTEM_PROMPT), HumanMessage(contentstate[user_prompt]) ] state[messages] ret llm_Tongyi.invoke(messages) action _create_agent_action(ret) if action: return {messages: [ret], actions: [action], output: } return {messages: [ret], output: ret.content}这里的设计体现了 CodeAct 的核心判断逻辑有代码块→ 提取代码设置 actionoutput为空 → 进入执行流程无代码块→ 模型直接给出了文本答案 →output赋值 → 循环终止_create_agent_action函数利用 Markdown 代码块标记python 来识别和提取代码。这是一个巧妙的约定大模型在生成代码时自然会使用 Markdown 格式包裹无需额外的格式约束。3.4 代码执行引擎Python 的 exec() 之力tool def execute_python(code: str) - str: 执行Python代码并返回结果。 try: local_vars {} exec(code, {}, local_vars) result local_vars.get(result, 执行成功) return str(result) except Exception as e: return fError executing code: {str(e)}这是整个 CodeAct 系统中最危险也最强大的组件。几个关键设计决策1.exec()的沙箱隔离exec(code, {}, local_vars)第二个参数{}是全局命名空间传入空字典意味着执行的代码无法访问外部全局变量第三个参数local_vars是局部命名空间代码执行后的所有变量都存在这里。这提供了一层基础的隔离。2. 统一的结果提取result local_vars.get(result, 执行成功)通过约定result变量名建立了代码 → 结果的标准化通道。如果代码没有定义result例如只是执行了某些操作则返回执行成功作为默认值。3. 错误容忍except Exception as e: return fError executing code: {str(e)}代码执行错误不会导致系统崩溃而是将错误信息作为结果返回给 LLM。模型可以根据错误信息修改代码重试——这正是自我纠错循环的基础。3.5 条件路由决定继续还是终止def enter_process(state: OverallState): if state[output] ! : return END return process_node路由逻辑简洁明了output非空 → LLM 已给出最终答案 → 结束output为空 → LLM 生成了代码 → 进入执行节点3.6 执行节点运行代码并回传结果def process_node(state: OverallState): actions state[actions] for action in actions: tool_name action[tool] tool_input action[tool_input] tool_fn next(t for t in tools if t.name tool_name) observation tool_fn.invoke(tool_input) state[messages].append( HumanMessage(contentf##执行结果:\n{observation}) ) return state执行完代码后结果以HumanMessage的形式追加到消息列表中。这样在下一轮 LLM 调用时模型就能看到代码的执行结果并据此决定是否满意、是否需要继续。3.7 图编排将所有节点串联graph StateGraph(OverallState) graph.add_node(llm_call, llm_call) graph.add_node(enter_process, enter_process) graph.add_node(process_node, process_node) graph.add_edge(START, llm_call) graph.add_conditional_edges(llm_call, enter_process) graph.add_edge(process_node, llm_call) agent graph.compile()LangGraph 的声明式 API 使得整个流程一目了然START → llm_call入口llm_call → enter_process条件路由process_node → llm_call执行完代码后回到 LLM形成闭环四、一次完整的执行轨迹以请计算 1~100 的和为例展示一次典型的 CodeAct 执行过程第 1 轮LLM 生成代码用户请计算1~100的和 LLM 回复 我来编写代码计算1到100的和 python result sum(range(1, 101))**系统提取代码并执行** code-snippet__js # 提取的代码 result sum(range(1, 101)) # 执行结果 5050第 2 轮LLM 收到结果给出答案系统反馈##执行结果: 5050 LLM 回复 1到100的和是 **5050**。 这个结果可以用高斯求和公式验证n(n1)/2 100×101/2 5050。由于第 2 轮回复中没有代码块output被赋值循环结束。五、CodeAct vs Function Calling vs ReAct维度Function CallingReActCodeAct行动空间有限预定义工具集有限预定义工具集无限任意 Python 代码灵活性低中高安全性高工具经过审核高需额外防护代码可执行任意操作错误恢复受限受限强可修改代码重试可解释性低高Thought 链高代码即逻辑模型要求需支持 tools API较低需要强代码生成能力适用场景标准化业务操作多步推理任务计算密集 / 数据处理 / 灵活任务CodeAct 的独特优势在于行动空间无限大不需要预测用户可能需要的所有工具代码本身就是万能工具。天然的自我纠错代码执行失败时错误信息是最精确的反馈模型可以针对性修复。可组合性强一段代码可以完成复杂的多步操作而 Function Calling 需要多轮调用。六、工程实践安全与可靠性6.1 代码执行的安全防护CodeAct 的最大风险在于exec()的使用。生产环境中建议沙箱隔离使用 Docker 容器或 subprocess 隔离代码执行环境避免恶意代码影响宿主系统。# 生产环境建议限制可用模块 safe_globals { __builtins__: { range: range, len: len, sum: sum, int: int, float: float, str: str, list: list, dict: dict, print: print, } } exec(code, safe_globals, local_vars)执行超时为代码执行设置时间限制防止死循环。资源限制限制内存使用和文件系统访问。6.2 循环次数上限防止 LLM 陷入无限的生成代码 → 报错 → 修改 → 报错循环MAX_ITERATIONS 5 iteration 0 while iteration MAX_ITERATIONS: # ... CodeAct 循环逻辑 iteration 16.3 结果校验不能完全信任代码执行的结果建议加入基础校验类型检查结果是否为预期类型范围检查数值结果是否在合理范围内长度限制输出内容是否过长防止内存溢出七、LangGraph 的设计哲学CodeAct 的实现选择 LangGraph 并非偶然。LangGraph 的三个特性与 CodeAct 天然契合状态管理MessagesState和add_messages自动处理对话历史的追加与合并无需手动管理。条件路由add_conditional_edges让继续执行和终止输出的分支逻辑声明化。图编排复杂的循环逻辑通过节点和边的组合清晰表达易于理解和扩展。相比用while True手写循环LangGraph 的状态图方案有两个优势可视化调用graph.get_graph().draw_mermaid()可直接生成流程图。可扩展添加新节点如日志记录、安全检查只需增加节点和边不影响已有逻辑。八、扩展思路8.1 增强代码能力当前实现的exec()使用空的全局命名空间意味着模型生成的代码无法import外部库。可以根据场景开放特定库import_whitelist {numpy: __import__(numpy), math: __import__(math)} exec(code, {__builtins__: __builtins__, **import_whitelist}, local_vars)8.2 多步代码编排当前实现每轮只提取一个代码块。可以扩展为支持多个代码块的顺序执行或支持模型在一次回复中定义多个函数再调用。8.3 与 Function Calling 融合CodeAct 和 Function Calling 并非互斥。可以设计混合架构对于标准化操作数据库查询、API 调用使用预定义的 Function Calling对于灵活的计算和数据处理使用 CodeAct 动态生成代码这样既保证了常见操作的可靠性又保留了应对长尾需求的灵活性。九、总结CodeAct 代表了 Agent 行动范式的一次重要跃迁从在菜单上点菜到自己下厨做菜。它的核心价值观是代码即行动Python 代码是最灵活、最强大的工具无需为每种需求预定义函数。执行即验证代码的执行结果是最客观的反馈错误信息是最精确的改进指引。循环即智能生成 → 执行 → 观察 → 修正的闭环赋予了 Agent 自我进化的能力。当然这种强大的灵活性也带来了安全方面的挑战。在实际落地时必须在放权与管控之间找到平衡——既要充分发挥代码执行的威力又要通过沙箱、白名单、超时等机制保证系统安全。在 AI Agent 的技术栈中CodeAct 或许不会完全取代 Function Calling但它为我们打开了一扇新的窗户当大模型足够聪明时让它自己写代码解决问题可能比我们预设所有工具更加高效。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】