从零搭建Agent智能体：新手避坑指南与实战演练

1次阅读

共计 2140 个字符，预计需要花费 6 分钟才能阅读完成。

开发者在初次接触 Agent 智能体时，往往难以理解其与传统脚本程序的核心区别。具体而言，传统脚本是线性执行的指令集合，而智能体则具备环境感知、自主决策和持续学习三大特征。这种差异导致开发者在以下环节频繁踩坑：

消息路由(Message Routing)：误用全局变量传递上下文，导致多轮对话状态混乱
上下文维护(Context Preservation)：未实现对话历史的有效压缩和存储，引发内存溢出
工具调度(Tool Dispatching)：同步调用阻塞主线程，造成系统假死

框架	扩展性(Extensibility)	学习曲线(Learning Curve)	适用场景(Use Case)
LangChain	★★★★★	★★★☆☆	复杂业务流程编排
AutoGPT	★★☆☆☆	★★★★★	快速原型开发
SemanticKernel	★★★★☆	★★★☆☆	企业级知识管理

from typing import Dict, List, Callable
from enum import Enum, auto

class AgentState(Enum):
    IDLE = auto()
    RUNNING = auto()
    ERROR = auto()

class BaseAgent:
    def __init__(self, max_context_size: int = 10):
        self._state = AgentState.IDLE
        self._tools: Dict[str, Callable] = {}
        self._context = []
        self._max_context = max_context_size

    def add_tool(self, name: str, func: Callable) -> None:
        """工具注册 (tool registration) 方法"""
        if not callable(func):
            raise TypeError('Tool must be callable')
        self._tools[name] = func

    def _change_state(self, new_state: AgentState) -> None:
        """状态机转换逻辑"""
        if self._state == AgentState.ERROR and new_state != AgentState.IDLE:
            raise RuntimeError('Cannot transit from ERROR state')
        self._state = new_state

会话上下文溢出(Context Overflow)

def add_to_context(self, message: str):
    # 使用 LRU 策略维护固定长度上下文
    if len(self._context) >= self._max_context:
        self._context.pop(0)
    self._context.append(message)

工具调用死锁(Tool Deadlock)

async def execute_tool(self, tool_name: str):
    if tool_name not in self._tools:
        raise KeyError(f'Tool {tool_name} not registered')

    # 异步执行防止阻塞
    return await asyncio.to_thread(self._tools[tool_name])

状态不一致(State Inconsistency)

def safe_execute(self, operation: Callable):
    try:
        self._change_state(AgentState.RUNNING)
        result = operation()
        self._change_state(AgentState.IDLE)
        return result
    except Exception as e:
        self._change_state(AgentState.ERROR)
        raise

采用双向链表 + 哈希表的混合数据结构实现 O(1)时间复杂度的 LRU 缓存：

from collections import OrderedDict

class ContextCache:
    def __init__(self, capacity: int):
        self._cache = OrderedDict()
        self._capacity = capacity

    def add(self, key: str, value: str):
        if key in self._cache:
            self._cache.move_to_end(key)
        else:
            if len(self._cache) >= self._capacity:
                self._cache.popitem(last=False)
            self._cache[key] = value