纯Python手写AI Agent是否可行与工程实践

agent-">一、问题背景：AI Agent开发是否必须依赖框架

在真实工程项目中，不使用常见的智能体编排框架或可视化流程编排工具，仅使用Python与LLM API手动实现AI Agent，不仅完全可行，在许多场景下甚至是更优选择。越来越多技术团队开始反思：当任务本质上是字符串处理、接口调用和循环控制时，引入庞大框架究竟是降低复杂度，还是制造新的复杂度？

这一判断并非孤立的工程偏好。Anthropic在其官方文档《Building Effective Agents》中给出了相当明确的建议：框架通过简化标准底层任务降低了入门门槛，但往往会创建额外的抽象层，遮蔽底层的提示词与响应内容，使调试更加困难；同时，框架还容易诱使开发者在简单方案已经足够的情况下引入不必要的复杂性。因此，Anthropic建议开发者从直接使用LLM API开始，因为许多模式只需少量代码即可实现。

这一立场与其他厂商形成了有趣的光谱分布：有的厂商持谨慎态度，明确建议直接调用API；有的厂商选择提供轻量SDK，强调“代码优先”，避免过度抽象；有的厂商则支持多框架互操作；还有的厂商最为推崇框架化使用。不同立场背后，反映的是对“抽象收益”与“抽象成本”的不同权衡。

二、从真实项目看框架移除的动机

一些生产环境团队在深度使用框架约12个月后，选择将框架从核心链路中完全移除。移除后，团队反馈的开发体验和交付效率不降反升。这不是个别现象，也并非否定框架价值，而是揭示了一个常被忽略的事实：框架为标准化场景提供便利，却为定制化场景带来隐性约束。

具体而言，框架被移除的动机通常集中在以下方面：

第一，调试成本。当框架将提示词拼装、消息历史管理、工具调用解析等过程封装在多层抽象之后，开发者在排查“模型为什么输出了错误结果”时，往往需要穿透框架内部逻辑。问题定位的路径变长，调试效率下降。

第二，灵活性受限。框架的设计总是面向一类通用问题，而真实业务需求常常表现出“非标准”特征。例如，某些任务需要在循环中动态调整系统提示词，某些场景需要在工具调用前插入自定义校验逻辑。框架若无法提供合适的扩展点，开发者就不得不绕过框架，反而造成架构上的割裂。

第三，版本演进与学习成本。框架快速迭代会带来API变更、概念更新和文档迁移成本。对于规模不大或长期维护的项目而言，持续跟随框架演进并不总是划算的。

三、框架到底解决了什么问题

要客观判断“是否需要框架”，必须先理解框架试图解决的核心痛点。

从技术抽象角度看，主流框架提供的核心能力可归纳为五类：

1. 统一模型接口：将不同LLM提供方的请求格式、鉴权方式、响应结构进行封装，降低供应商切换成本。
2. 多步骤串联：将多个模型调用、数据转换步骤组织为链式流程，使复杂任务具有可读的结构。
3. 工具调用：定义统一的工具描述格式，并处理模型输出到实际函数执行的映射。
4. 状态管理：在多轮对话或长任务中维护状态、记忆与上下文窗口。
5. 自主决策循环：让模型在“观察—决策—行动”的循环中推进任务，直到满足终止条件。

另一类面向复杂工作流的框架则进一步提供：状态图编排、条件分支、检查点恢复、人工介入等高级能力。这类能力对于长运行任务和复杂分支确实有价值，但同样意味着更高的学习曲线和运维成本。

值得强调的是，上述能力并非只有通过框架才能获得。Python原生能力结合LLM API，完全可以在一个可控制的代码规模内实现这些需求的“够用版本”。

四、纯Python实现AI Agent的核心模块

一个不依赖重型框架的AI Agent，通常只需要清晰实现以下核心模块。

4.1 模型调用封装

模型调用封装的核心目标是统一请求入口，而不是构建庞大适配层。一个轻量的封装函数即可满足大部分需求：

def call_model(messages, tools=None, temperature=0.2):
    """统一调用LLM，返回归一化结果。"""
    if tools is None:
        tools = []
    response = llm_client.chat.completions.create(
        model=MODEL_NAME,
        messages=messages,
        tools=tools,
        temperature=temperature,
    )
    return response.choices[0].message

这一层封装的价值在于：为所有模型调用提供一个稳定的内部接口。当需要调整参数、增加日志或切换模型时，只需修改一处，而无需改动业务逻辑。与框架的全面抽象不同，这里的封装程度由业务需求决定，避免“为不存在的复杂性买单”。

4.2 提示词与消息管理

AI Agent的大部分行为由提示词驱动。手动管理提示词意味着开发者对输入内容拥有完全可见性。建议将系统提示词作为独立模块维护，并将消息历史显式管理：

class ConversationMemory:
    def __init__(self, system_prompt: str, max_turns: int = 20):
        self.system_prompt = system_prompt
        self.max_turns = max_turns
        self.history = []
    def get_messages(self):
        return [
            {"role": "system", "content": self.system_prompt}
        ] + self.history[-self.max_turns * 2:]
    def add_user_message(self, content: str):
        self.history.append({"role": "user", "content": content})
    def add_assistant_message(self, content: str):
        self.history.append({"role": "assistant", "content": content})

这种方式直接对应LLM API的消息结构，调试时打印或检查消息列表即可，不需要理解框架内部的状态存储机制。

4.3 工具定义与执行

工具是AI Agent连接外部世界的桥梁。纯Python实现的工具系统非常直观：定义普通函数，使用JSON Schema描述参数，并将模型输出中的工具调用请求映射到函数执行。

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "query_order_status",
            "description": "查询订单状态",
            "parameters": {
                "type": "object",
                "properties": {
                    "order_id": {"type": "string"}
                },
                "required": ["order_id"]
            }
        }
    }
]
def execute_tool(name: str, arguments: dict):
    """根据工具名分发到实际函数。"""
    if name == "query_order_status":
        return query_order_status(arguments["order_id"])
    raise ValueError(f"Unknown tool: {name}")

相比框架，这种方式的优势在于工具执行链路完全透明。开发者可以直接在工具函数上设置断点、记录日志、进行单元测试，而无需关心框架的调度逻辑。

4.4 Agent循环控制

Agent循环是智能体能力的集中体现。一个清晰的while循环即可表达“模型决策—执行工具—反馈结果”的核心流程：

def run_agent(user_input: str, max_iterations: int = 10) -> str:
    memory = ConversationMemory(SYSTEM_PROMPT)
    memory.add_user_message(user_input)
    for _ in range(max_iterations):
        messages = memory.get_messages()
        response = call_model(messages, tools=TOOLS)
        if response.tool_calls:
            memory.add_assistant_message(response)
            for tool_call in response.tool_calls:
                result = execute_tool(
                    tool_call.function.name,
                    eval(tool_call.function.arguments)
                )
                memory.add_tool_result(result)
            continue
        memory.add_assistant_message(response.content)
        return response.content
    return "任务达到最大迭代次数限制"

这个循环结构简洁但完整。它涵盖了Agent的核心行为模式：模型决策、工具调用、结果反馈、终止判断。当业务需求需要更复杂的控制逻辑时，开发者可以在循环内直接扩展，无需与框架的控制流机制搏斗。

五、轻量实现与框架的取舍边界

纯Python手写Agent并非“反框架”的教条。更准确的理解是：抽象层级应当与问题复杂度匹配。

对于以下场景，轻量实现具有明显优势：

• 任务流程相对固定，分支逻辑有限；
• 团队规模较小，对代码可读性要求高；
• 需要深度定制调试与观测能力；
• 模型调用次数不多，对编排能力的要求较低。

而在以下场景中，考虑使用框架仍然是务实的选择：

• 需要复杂状态机与长任务断点恢复；
• 多Agent之间的动态协作与任务委派；
• 需要可视化的流程编排与监控面板；
• 团队已有框架使用经验且迁移成本可控。

关键判断标准并不是“哪个技术更先进”，而是“抽象带来的收益是否超过它带来的复杂度”。许多项目在早期依赖框架快速搭建原型，但在产品化过程中却逐渐发现：框架的通用逻辑与业务特殊需求之间的摩擦持续增长，最终剥离框架反而获得更清晰的掌控力。

六、实践建议

从工程实践角度，以下原则值得参考：

从直接API调用开始。 先使用Python与LLM API完成最小可用版本，观察任务本质复杂度。很多需求在几十行代码内即可收敛，此时引入框架只是增加层次。

保持消息与提示词可见。 无论是否使用框架，提示词内容、消息历史和模型输出的完整可见性，是调试Agent行为的基础。

工具系统保持薄封装。 工具函数的定义与执行分发逻辑应尽量扁平，避免设计复杂的工具注册机制。薄封装换来的是可测试性和可追踪性。

渐进式引入复杂度。 只有在出现明确的框架级需求（如检查点恢复、复杂分支编排、多Agent协作）时，才评估引入对应能力。架构演进应从实际痛点出发，而不是从技术想象出发。

将框架能力视为选装模块而非默认基础。 现代Agent开发的一个务实思路是：以轻量代码为骨架，按需引入可插拔的增强能力，而不是从第一天就绑定在某个完整框架体系上。

总结而言，纯Python + LLM API手动实现AI Agent不仅可行，而且在大量真实工程场景中是一种更直接、更易调试、更具掌控力的路径。框架的价值应当被尊重，但它并非构建Agent的必需品。回到问题本质——Agent由提示词、消息、工具和循环构成，而这些，Python原生足以承载。