CodeAct：超越React Agent架构的新范式
大家好，我是你们的AI博主矩深AI。今天要和大家聊一个最近在AI圈里非常火的概念——CodeAct架构。
如果你对AI智能体（Agent）或者大语言模型（LLM）的应用感兴趣，那这篇文章可千万别错过！
传统Agent架构的痛点
在深入CodeAct之前，我们先来看看传统方式的问题所在。
想象一下，你有一个超级聪明的AI助手，想让它帮你做些复杂的事情，比如：
- 查询北京今天的天气
- 根据天气情况推荐合适的活动 再帮你预订相关场所
传统方式一：JSON函数调用 📋
{
"action": "get_weather",
"location": "北京"
}
问题在哪？
- ❌ 像填表格一样死板，只能选择预设好的动作
- ❌ 无法灵活组合多个操作
- ❌ 想要复杂任务？抱歉，需要多次调用，超级繁琐
传统方式二：纯文本指令 💬
用户：请帮我查一下北京的天气，然后根据天气推荐活动
问题在哪？
- ❌ 需要额外的理解层，容易出错
- ❌ 步骤多，效率低
- ❌ 灵活性依然受限
现在，让我们看看CodeAct是如何颠覆这一切的！
什么是CodeAct？
CodeAct 是由Manus官方提出并采用的一种新型Agent架构。它实现了 JSON 函数调用的替代方案，可以以更少的步骤解决更复杂的任务。这是通过利用图灵完备编程语言的全部功能来组合和转换多个工具的输出来实现的。
简单来说，它用了一种更聪明的方式，让AI能够完成更加复杂的任务，而且往往只需要更少的步骤。它是怎么做到的呢？答案是——让AI直接编写和运行Python代码！
核心思想: 让大语言模型（LLM）通过写和运行真实的 Python 代码来与外部世界（工具、数据、API）互动，而不是用死板的 JSON 或纯文本指令。
CodeAct 怎么解决？
简单说：让Agent直接写 Python 代码！
代码就是行动：
CodeAct 把 Agent“想法”直接变成可执行的 Python 代码。比如助手想查天气，它就直接生成一段代码：
weather = get_weather("北京")
print(weather)
万能“翻译官”（Python 解释器）：
系统内置一个 Python 解释器。Agent写的代码会被这个解释器真正运行。解释器负责：
调用真实的工具（
get_weather背后连接着真实的天气 API）。
处理数据（比如读取文件、做计算
value = add(1,2)。 执行逻辑（if…else…, for 循环）。
边做边看，错了就改（多轮交互）：这是关键优势！
助手不是一次性写完所有代码就完事。 它先写一段代码,解释器运行这段代码。
解释器把运行结果反馈给助手。助手看到结果后： 如果结果符合预期，就接着写下一段代码。如果出错了或者结果不对，它就能立刻修改前面的代码或写新代码来修正。
如此反复，直到完成任务。这就像程序员在调试程序一样！
CodeAct和传统方式对比
传统方式（JSON/Text）： 你是一个指挥官，手下有几个员工（固定工具）。你每次只能给一个员工发一条非常具体的指令。想完成复杂任务需要反复发令，配合困难。
CodeAct： 你是一个指挥官，手下有一个万能机器人。你直接给机器人写一个程序脚本（Python 代码），告诉它整个任务流程。机器人能自己按脚本执行，遇到问题还会实时报告请示。你只需要在关键节点做决策或修改脚本。
代码样例
langchain官方已经开源实现codeact的库：langgraph-codeact
langgraph-codeact开源地址：https://github.***/langchain-ai/langgraph-codeact
langchain是一个极其优雅、易用、专业的大模型开发框架，并不像一些只了解点皮毛就开始批判 langchain某某缺点的人说的那么不堪，据我所知，字节跳动 官方就使用的langchain进行开发产品。
（下面代码需要有一定python基础和langchain基础）
安装
pip install langgraph-codeact
示例代码
1. 定义工具
def get_weather(city: str) -> str:
"""获得城市的天气信息，返回值的格式形如：多云 17度"""
if city == "南京":
return "晴天 30度"
else:
return "暴雨 27度"
def add(a: float, b: float) -> float:
"""将两个数字相加。"""
return a + b
def subtract(a: float, b: float) -> float:
"""两个数字相减。"""
return a - b
def multiply(a: float, b: float) -> float:
"""将两个数字相乘。"""
return a * b
def divide(a: float, b: float) -> float:
"""将两个数相除。"""
return a / b
tools = [add, multiply, divide, subtract, get_weather]
2. 实现代码运行逻辑 eval
import builtins
import contextlib
import io
from typing import Any
def eval(code: str, _locals: dict[str, Any]) -> tuple[str, dict[str, Any]]:
# 执行前存储原始密钥
original_keys = set(_locals.keys())
try:
with contextlib.redirect_stdout(io.StringIO()) as f:
exec(code, builtins.__dict__, _locals)
result = f.getvalue()
if not result:
result = "<code ran, no output printed to stdout>"
except Exception as e:
result = f"Error during execution: {repr(e)}"
# 确定执行期间创建的新变量
new_keys = set(_locals.keys()) - original_keys
new_vars = {key: _locals[key] for key in new_keys}
return result, new_vars
3. 创建CodeAct Agent
from langgraph_codeact import create_codeact
from langgraph.checkpoint.memory import MemorySaver
from langchain_openai import ChatOpenAI
model = ChatOpenAI(model="qwen3")
from langchain_core.tools import tool as create_tool
from langchain_core.tools import StructuredTool
import inspect
# 我这里将提示词翻译为中文，替换默认提示词，对中文模型更友好
def create_prompt(tools: list[StructuredTool], base_prompt: Optional[str] = None):
"""Create default prompt for the CodeAct agent."""
tools = [t if isinstance(t, StructuredTool) else create_tool(t) for t in tools]
prompt = f"{base_prompt}\n\n" if base_prompt else ""
prompt += """# 你将收到一个待完成的任务。你应输出以下内容之一：
- 一段能够解决该任务或向解决方案迈进一步的 Python 代码片段。任何希望从代码中提取的输出都应通过 print方法 打印到控制台。代码须用围栏代码块包裹。
- 直接展示给用户的文字，用于请求更多信息或给出最终答案。
## 除了 Python 标准库外，你还可以使用以下函数：
"""
for tool in tools:
prompt += f'''
def {tool.name}{str(inspect.signature(tool.func))}:
"""{tool.description}"""
...
'''
prompt += """---
先前代码片段中在顶层定义的变量，可直接在你的代码里引用。
提醒：请使用 Python 代码片段来调用工具。"""
return prompt
prompt = create_prompt(tools=tools)
code_act = create_codeact(model, tools, eval, prompt=prompt)
agent = code_act.***pile(checkpointer=MemorySaver())
4. 运行CodeAct Agent
messages = [
{
"role": "user",
"content": "北京的天气怎么样，如果再升高六度是多少度",
}
]
for typ, chunk in agent.stream(
{"messages": messages},
stream_mode=[
"values",
],
config={"configurable": {"thread_id": 1}},
):
if typ == "values":
print("\n\n---answer---\n\n", chunk)
5. 展示完整的提示词模板
我们会看到下面模型在执行过程的上下文
<|im_start|>system
# 你将收到一个待完成的任务。你应输出以下内容之一：
- 一段能够解决该任务或向解决方案迈进一步的 Python 代码片段。任何希望从代码中提取的输出都应通过 print方法 打印到控制台。代码须用围栏代码块包裹。
- 直接展示给用户的文字，用于请求更多信息或给出最终答案。
## 除了 Python 标准库外，你还可以使用以下函数：
def add(a: float, b: float) -> float:
"""将两个数字相加。"""
...
def multiply(a: float, b: float) -> float:
"""将两个数字相乘。"""
...
def divide(a: float, b: float) -> float:
"""将两个数相除。"""
...
def subtract(a: float, b: float) -> float:
"""两个数字相减。"""
...
def get_weather(city: str) -> str:
"""获得城市的天气信息，返回值的格式形如：多云 17度"""
...
---
先前代码片段中在顶层定义的变量，可直接在你的代码里引用。
提醒：请使用 Python 代码片段来调用工具。<|im_end|>
<|im_start|>user
北京的天气怎么样，如果再升高六度是多少度<|im_end|>
<|im_start|>assistant
``python
# 获取北京的天气
weather = get_weather("北京")
print(f"北京的天气是：{weather}")
# 提取温度部分：假设格式为“[天气] [数字]度”或“[数字]度”
import re
# 使用正则表达式提取数字
temperature_match = re.search(r'(\d+)度', weather)
if temperature_match:
current_temperature = float(temperature_match.group(1))
print(f"当前温度是：{current_temperature}度")
# 计算升高六度后的温度
new_temperature = add(current_temperature, 6)
print(f"如果再升高六度，北京的温度将是：{new_temperature}度")
else:
print("无法解析温度信息。")
``<|im_end|>
<|im_start|>user
北京的天气是：暴雨 27度
当前温度是：27.0度
如果再升高六度，北京的温度将是：33.0度
<|im_end|>
<|im_start|>assistant
北京的天气是：暴雨 27度
当前温度是：27.0度
如果再升高六度，北京的温度将是：33.0度
我们观察发现，模型的推理过程完全以写代码的方式，非常优美。
总结
CodeAct 的核心思想是：让大语言模型（LLM）使用真实、可执行的 Python 代码作为其行动的表达方式，并通过集成的 Python 解释器实时运行这些代码、获取反馈结果。
这种架构实现了编写代码 → 执行 → 观察结果 → 修正代码/编写新代码 → 再次执行的闭环交互流程。通过这种方式，LLM 能够以高度灵活和强大的姿态，充分利用现有的软件工具和库资源，自主完成复杂的多步骤任务，并具备自主调试和纠错的能力。
本质上，CodeAct 巧妙地将 LLM 的高级规划推理能力与 Python 生态系统的丰富功能进行了深度融合，为智能体处理复杂问题提供了一种全新的范式。
- PS：都看到这里，来个点赞、关注吧。 您的支持是我坚持的最大动力！
