从头开始构建 AI 代理：架构、框架和最佳实践

代理设计模式

在编写一行代码之前，了解 AI 代理的基本设计模式至关重要。这些模式定义了代理如何推理、计划和执行任务，选择正确的模式决定了代理系统的功能和限制。

ReAct 模式（推理 + 行动）

ReAct 是基于 LLM 的代理最广泛采用的模式。它将推理（思考）与行动（工具使用）交错在一个连续的循环中。在每个步骤中，代理：

1. 观察当前状态（用户输入、之前的工具结果）
2. 思考下一步该做什么（链式推理）
3. 通过调用工具或提供响应来采取行动
4. 观察结果并重复

ReAct 模式很优雅，因为它利用了 LLM 在文本中推理的自然能力，同时将该推理建立在现实世界的观察中。它擅长执行下一步取决于前一步结果的任务，例如研究、调试或数据分析。

计划和执行

计划和执行模式将计划与执行分为不同的阶段。首先，规划代理分析任务并生成具有有序步骤的结构化计划。然后，执行代理执行每个步骤，并将结果报告给规划者。计划者可以根据结果修改计划。

该模式非常适合复杂的多步骤任务，在这些任务中，预先规划可以减少错误和浪费精力。它还提供了更好的透明度，因为计划可以在执行开始之前由人类进行审查。

思想树

思想树通过同时探索多个推理路径来扩展思想链推理。该代理会生成几种候选方法，对每种方法进行评估，并在修剪死胡同的同时追求最有希望的路径。这种模式对于创造性地解决问题和使用多种有效方法的任务很有价值。

反射

反射模式向代理循环添加了一个自评估步骤。完成任务或子任务后，代理会批评自己的输出，识别弱点或错误，并迭代以改进结果。这对于质量比速度更重要的编写、代码生成和分析任务特别有效。

AI 代理的构建模块

每个 AI 代理系统都需要四个基础组件，这些组件协同工作以实现自主行为。

LLM Backbone

大语言模型充当推理引擎。 LLM 的选择会显着影响代理功能：

• Claude (Anthropic)：擅长复杂推理、工具使用和遵循详细说明。 强大的安全特性使其适合处理敏感操作的生产代理
• GPT-4 (OpenAI)：强大的工具调用、广泛的第三方生态系统以及跨不同任务的强大性能
• 开源型号（Llama、Mistral）：提供对部署和成本的完全控制，适合需要在本地或本地运行的代理高容量

工具集成

工具将代理从文本生成扩展到现实世界的交互。精心设计的工具界面包括：

• 清晰的描述性工具名称和文档，帮助 LLM 了解何时使用每个工具
• 结构化输入模式，并进行验证以防止格式错误的调用
• 错误处理，返回 LLM 可以对
执行操作的信息性消息
• 超时和速率限制防止失控操作

内存系统

对于跨会话操作或处理长时间任务的代理，内存系统至关重要。使用以下实现存储器：

• 对话缓冲区：将完整的对话历史记录保留在 LLM 上下文中（简单但受上下文窗口限制）
• 摘要存储器：定期总结较旧的对话轮流以压缩上下文
• 矢量存储：嵌入并存储重要信息，以便在相关时进行语义检索
• 持久文件：将关键决策和事实写入跨会话持久保存的文件

编排层

编排层管理代理循环、工具执行、错误恢复以及与外部系统的交互。它处理：

• LLM 的消息格式化和上下文管理
• 工具调用解析、执行和结果注入
• 重试逻辑和错误恢复
• 日志记录、监控和可观察性
• 人机交互批准敏感操作

分步：在 Python 中构建基本代理

让我们使用 Python 和 Anthropic API 从头开始构建一个简单的 ReAct 代理。此示例演示了没有框架依赖性的核心概念。

步骤 1：定义您的工具

import anthropic
import json

# Define tools the agent can use
tools = [
    {
        "name": "search_web",
        "description": "Search the web for current information on a topic",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "The search query"
                }
            },
            "required": ["query"]
        }
    },
    {
        "name": "calculate",
        "description": "Perform a mathematical calculation",
        "input_schema": {
            "type": "object",
            "properties": {
                "expression": {
                    "type": "string",
                    "description": "Mathematical expression to evaluate"
                }
            },
            "required": ["expression"]
        }
    }
]

步骤 2：实施工具执行

def execute_tool(tool_name, tool_input):
    """Execute a tool and return the result."""
    if tool_name == "search_web":
        # Replace with actual search API integration
        return search_api(tool_input["query"])
    elif tool_name == "calculate":
        try:
            result = eval(tool_input["expression"])  # Use safe eval in production
            return str(result)
        except Exception as e:
            return f"Error: {str(e)}"
    return "Unknown tool"

步骤 3：构建代理循环

def run_agent(user_message, max_iterations=10):
    client = anthropic.Anthropic()
    messages = [{"role": "user", "content": user_message}]
    
    system_prompt = """You are a helpful AI agent. Use the available tools 
    to research and answer questions accurately. Think step by step."""
    
    for i in range(max_iterations):
        response = client.messages.create(
            model="claude-sonnet-4-20250514",
            max_tokens=4096,
            system=system_prompt,
            tools=tools,
            messages=messages
        )
        
        # Check if the agent wants to use a tool
        if response.stop_reason == "tool_use":
            # Extract tool calls from response
            tool_results = []
            for block in response.content:
                if block.type == "tool_use":
                    result = execute_tool(block.name, block.input)
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": result
                    })
            
            # Add assistant response and tool results to messages
            messages.append({"role": "assistant", "content": response.content})
            messages.append({"role": "user", "content": tool_results})
        else:
            # Agent is done, return final response
            return response.content[0].text
    
    return "Agent reached maximum iterations"

多代理编排模式

对于复杂的工作流程，通常需要单个代理功亏一篑。多代理系统将工作分配给协作解决问题的专业代理。

顺序管道

代理以线性顺序处理任务，每个代理将其输出传递给下一个。例如：研究代理收集信息，分析代理处理信息，写作代理生成最终报告。这种模式简单且可预测，但缺乏并行性。

主管模式

主管代理管理一组工作代理、委派任务并聚合结果。主管根据当前任务要求决定聘用哪名工人。该模式提供了强大的控制能力，非常适合角色边界清晰的工作流程。

协作讨论

多个座席参与结构化讨论，每个座席都贡献自己的专业观点。主持人代理管理对话流并综合最终输出。这种模式擅长于需要不同专业知识的任务，例如代码审查或战略规划。

分层委派

代理按层次结构组织，高级代理将任务分解并委派给较低级别​​的专家。每个级别都可以进一步分解和委派，创建协调工作树。这种模式可以很好地适应大型、复杂的项目。

评估和测试 AI 代理

由于 LLM 输出的不确定性，测试 AI 代理与测试传统软件有根本不同。

单元测试工具

使用已知输入和预期输出单独测试每个工具。工具测试应该是确定性的，并涵盖边缘情况，包括错误条件、格式错误的输入和超时场景。

轨迹测试

记录并评估代理完成任务所采取的操作顺序。良好的轨迹测试验证智能体是否遵循合理的路径，而不仅仅是达到正确的答案。将轨迹与专家定义的黄金路径进行比较。

端到端评估

针对具有已知正确结果的基准任务套件运行完整代理。衡量成功率、平均步骤数、工具调用效率和每项任务的成本。随着时间的推移跟踪这些指标以检测回归。

对抗性测试

使用对抗性输入测试代理，包括提示注入尝试、不明确的指令、不可能的任务和冲突的要求。 验证代理是否妥善处理这些问题，而不会产生有害输出或进入无限循环。

生产部署注意事项

将 AI 代理从原型转移到生产需要解决几个关键问题。

成本管理

LLM API 调用是 AI 代理的主要成本驱动因素。通过以下方式控制成本：

• 设置每个任务的最大迭代限制
• 使用较小的模型进行例行推理，使用较大的模型进行复杂决策
• 实现重复工具调用和 LLM 查询的缓存
• 监控每个任务的成本并设置预算警报

可靠性和错误恢复

生产代理必须妥善处理故障：

• 针对瞬态 API 故障实施具有指数退避的重试逻辑
• 在主要工具不可用时设计回退策略
• 添加断路器以防止级联故障
• 记录所有代理操作以进行调试和审计跟踪

安全和防护

部署安全机制以防止代理采取有害操作：

• 需要人工批准才能进行高影响操作（财务交易、数据删除、外部通信）
• 实施允许的工具操作的白名单和禁止的操作的阻止列表
• 添加输出过滤以在敏感信息离开系统之前捕获该信息
• 设置针对异常代理行为的监控警报

可观察性

全面的可观察性对于了解和提高代理性能至关重要：

• 跟踪每个代理执行情况，包括所有推理步骤、工具调用和决策
• 跟踪延迟、令牌使用情况和每次交互成本
• 监控不同任务类型的成功率和失败模式
• 构建仪表板，使运营团队能够实时了解代理运行状况

Workstation 构建定制 AI 代理解决方案

在 Workstation，我们在为各行业的企业设计和部署生产 AI 代理系统方面拥有深厚的专业知识。我们的方法包括：

• 发现和设计：我们与您的团队合作，确定高价值的自动化机会，并设计与您现有基础设施集成的代理架构
• 快速原型制作：我们快速构建工作代理原型，使您能够在投入全面开发之前评估功能并提供反馈
• 生产工程：我们的团队可处理生产部署的复杂性，包括可靠性、安全性、成本优化和监控
• 定制工具开发：我们构建定制工具，将您的 AI 代理连接到内部系统、数据库、API 和第三方服务
• 持续优化：我们不断监控和改进您的代理系统，降低成本、提高准确性并随着时间的推移扩展功能

准备好构建可改变您的业务运营的 AI 代理了吗？通过info@workstation.co.uk联系我们，讨论您的需求，并了解我们的团队如何将您的 AI 代理愿景变为现实。