打造你的第一个AI智能体：从零理解工具调用与智能循环

你是否曾好奇过，AI智能体是如何通过工具调用完成复杂任务的？今天，我们将通过一个完整的代码实例，深入探讨智能体的工作原理，让你不仅能看懂代码，更能理解背后的设计思想。

一、智能体的核心：环境准备与安全设置

任何AI智能体的第一步都是环境配置。我们的代码展示了专业的环境变量管理方式：

def _set_env(var: str):
    """安全设置环境变量的辅助函数"""
    if not os.environ.get(var):
        os.environ[var] = getpass.getpass(f"{var}: ")

这里有两个值得学习的细节：

条件检查：先检查变量是否已存在，避免重复设置
安全输入：使用getpass.getpass()隐藏敏感信息输入

这种设计模式在真实项目中非常实用，特别是在处理API密钥等敏感信息时。

二、智能体的工具箱：功能与定义的分离

智能体的强大之处在于它能调用外部工具。让我们看看如何优雅地实现这一点：

1. 工具函数定义

1
2
3

def list_files() -> List[str]:
    """列出当前目录文件"""
    return os.listdir(".")

这里使用了类型提示（-> List[str]），这不仅让代码更易读，还能让IDE提供更好的代码补全。

2. 工具配置映射

tools = [
    {
        "type": "function",
        "function": {
            "name": "list_files",
            "description": "Returns a list of files in the directory.",
            "parameters": {"type": "object", "properties": {}, "required": []}
        }
    }
]

工具配置采用了OpenAI的function calling格式，这是当前大模型工具调用的标准方式。

3. 函数映射字典

tool_functions = {
    "list_files": list_files,
    "read_file": read_file,
    "terminate": terminate
}

这种映射设计实现了配置与实现的分离，让代码维护更加灵活。

三、智能体的记忆系统：对话历史管理

智能体的”记忆力”决定了它的上下文理解能力：

memory = [{"role": "user", "content": user_task}]

# 在每次交互后更新记忆
memory.extend([
    {"role": "assistant", "content": json.dumps(action)},
    {"role": "user", "content": json.dumps(result)}
])

记忆系统的关键点：

角色分离：清晰区分用户、助手和系统消息
JSON序列化：确保复杂数据结构可被正确传输
增量更新：逐步构建完整的对话历史

四、智能循环：决策与执行的舞蹈

这是智能体的核心逻辑，让我们拆解这个精妙的循环：

while iterations < max_iterations:
    # 1. 构建完整上下文
    messages = agent_rules + memory
    
    # 2. 调用大模型决策
    response = client.chat.completions.create(
        model=os.environ['MODEL_NAME'],
        messages=messages,
        tools=tools,
        max_tokens=1024
    )
    
    # 3. 处理工具调用
    if response.choices[0].message.tool_calls:
        # 提取并执行工具
        tool = response.choices[0].message.tool_calls[0]
        tool_name = tool.function.name
        tool_args = json.loads(tool.function.arguments)
        
        # 4. 执行并记录结果
        result = tool_functions[tool_name](**tool_args)
        print(f"Executing: {tool_name} with args {tool_args}")

这个循环体现了感知-决策-执行的经典AI范式：

感知：接收当前状态和记忆
决策：大模型分析情况，选择行动
执行：调用相应工具完成任务

五、安全机制：优雅的边界控制

优秀的智能体必须有完善的安全机制：

max_iterations = 10  # 防止无限循环

try:
    result = tool_functions[tool_name](**tool_args)
except Exception as e:
    result = {"error": f"Error executing {tool_name}: {str(e)}"}

多重保护机制：

迭代限制：避免死循环
异常处理：优雅处理工具执行错误
工具验证：检查工具是否存在

六、终止机制：完美的结束艺术

智能体需要知道何时停止：

def terminate(message: str) -> None:
    """终止智能体循环"""
    print(f"Termination message: {message}")

# 在循环中
if tool_name == "terminate":
    print(f"Termination message: {tool_args['message']}")
    break