如何使用 Python SDK 构建 OpenAI Agents：分步指南

深入了解 OpenAI 最新的 Assistants API，学习如何通过 Python 构建、管理和部署能够执行复杂任务的自主 AI Agents。本指南将从环境设置到高级工具使用，为您提供完整的实践路线图。

什么是 OpenAI Agents？

在人工智能领域，一个“Agent”不仅仅是一个简单的聊天机器人或 API 调用。它是一个被设计为能够自主实现目标的系统。OpenAI Agents（通过 Assistants API 实现）是这一理念的具体体现，它们能够理解指令、利用工具、并保持对话状态以完成多步骤任务。

与传统的 LLM 交互不同，Agents 引入了一个持久化和有状态的层面。您可以创建一个“Assistant”，为其配置特定的指令、模型和工具，然后通过“Thread”（对话线程）与其交互。这种结构使得 Agent 能够“记住”之前的对话，并利用这些信息来规划和执行后续步骤。

核心特性包括：

工具集成 (Tool Integration): 允许 Agent 调用外部函数或 API，例如查询数据库、获取实时天气或执行代码。这是 Agent 超越纯文本生成、与现实世界交互的关键。
持久化状态 (Persistent State): 通过 Thread 对象，对话历史被完整保存，使得 Agent 能够进行长期、复杂的交互，而不会“忘记”上下文。
自主规划与执行 (Autonomous Planning & Execution): Agent 能够根据目标自行决定何时以及如何使用其工具，并按顺序执行任务。
人机协作 (Human-in-the-Loop): 框架设计支持在关键节点暂停，等待人类输入或批准，即“切换”（Handoffs），确保了可控性与安全性。

准备您的开发环境

1. 安装 Python

确保您的系统中安装了 Python 3.8 或更高版本。您可以从 Python 官网下载并安装。建议使用虚拟环境来管理项目依赖。

2. 安装 OpenAI Python SDK

OpenAI 官方提供了 Python SDK，可以通过 pip 轻松安装。运行以下命令以安装或更新到最新版本：

pip install --upgrade openai

3. 获取您的 OpenAI API 密钥

要使用 API，您需要一个 API 密钥。登录您的 OpenAI 账户，在 API Keys 部分创建一个新的密钥。请务必妥善保管此密钥，不要在客户端代码中硬编码。最佳实践是将其设置为环境变量。

# 在 Linux 或 macOS 中
export OPENAI_API_KEY='your-api-key-here'

# 在 Windows (PowerShell) 中
$env:OPENAI_API_KEY='your-api-key-here'

SDK 会自动从该环境变量中读取密钥。

构建您的第一个 Agent：一个简单的“你好，Agent！”

让我们通过一个完整的示例来了解构建 Agent 的基本流程。这个 Agent 的任务很简单：作为一个友好的助手回答问题。我们将依次创建 Assistant、Thread、Message，然后运行它。

步骤 1: 创建一个 Assistant

Assistant 是 Agent 的配置蓝图。您在这里定义它的身份、指令和能力。

from openai import OpenAI

client = OpenAI()

assistant = client.beta.assistants.create(
    name="Math Tutor",
    instructions="You are a personal math tutor. Write and run code to answer math questions.",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4-turbo-preview"
)

步骤 2: 创建一个 Thread

Thread 代表一个独立的对话会话。为每个用户或每个任务创建一个新的 Thread。

thread = client.beta.threads.create()

步骤 3: 添加消息到 Thread

将用户的输入作为一条 Message 添加到 Thread 中。

message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="I need to solve the equation `3x + 11 = 14`. Can you help me?"
)

步骤 4: 运行 Assistant

创建一个 Run 来让 Assistant 处理 Thread 中的消息。这是一个异步操作，需要轮询检查其状态。

import time

run = client.beta.threads.runs.create(
    thread_id=thread.id,
    assistant_id=assistant.id
)

# Wait for the run to complete
while run.status in ['queued', 'in_progress']:
    run = client.beta.threads.runs.retrieve(
        thread_id=thread.id,
        run_id=run.id
    )
    time.sleep(0.5)

步骤 5: 显示 Assistant 的响应

一旦 Run 完成，新的消息（来自 Assistant）就会被添加到 Thread 中。我们只需获取并显示它。

if run.status == 'completed':
    messages = client.beta.threads.messages.list(
        thread_id=thread.id
    )
    # The latest message is the first in the list
    assistant_response = messages.data[0].content[0].text.value
    print(f"Assistant: {assistant_response}")
else:
    print(f"Run failed with status: {run.status}")

为您的 Agent 赋能：使用工具（函数调用）

Agent 真正的威力在于它能够与外部世界交互。这通过“工具”实现，在 OpenAI 的语境中，这通常指函数调用。当模型判断需要执行一个外部函数来回答问题时，它会暂停执行，并请求您调用该函数。您的代码需要处理这个请求，执行函数，然后将结果返回给 Agent，让它继续完成任务。

让我们构建一个能查询当前天气的 Agent。

1. 定义一个工具（Python 函数）

首先，我们定义一个本地 Python 函数。为了简单起见，这里我们模拟一个 API 调用。

import json

def get_current_weather(location, unit="celsius"):
    """Get the current weather in a given location"""
    # In a real app, you'd call a weather API here.
    weather_info = {
        "location": location,
        "temperature": "22",
        "unit": unit,
        "forecast": ["sunny", "windy"],
    }
    return json.dumps(weather_info)

2. 将工具注册到 Assistant

在创建 Assistant 时，通过 `tools` 参数描述您的函数。这包括函数名、描述和参数。这让模型知道它拥有这个工具以及如何使用它。

weather_assistant = client.beta.assistants.create(
    name="Weather Bot",
    instructions="You are a weather bot. Use the provided functions to answer weather questions.",
    model="gpt-4-turbo-preview",
    tools=[{
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "Get the current weather in a given location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                },
                "required": ["location"]
            }
        }
    }]
)

3. 处理 `requires_action` 状态

这是 Agent 循环的核心。当 Run 的状态变为 `requires_action` 时，意味着模型需要您执行一个或多个工具调用。您需要解析 `tool_calls`，执行相应的本地函数，然后将结果通过 `submit_tool_outputs` 提交回去。

# ... (create thread and message: "What's the weather in Tokyo?")
# ... (create run)

while True:
    run = client.beta.threads.runs.retrieve(thread_id=thread.id, run_id=run.id)

    if run.status == 'requires_action':
        tool_outputs = []
        for tool_call in run.required_action.submit_tool_outputs.tool_calls:
            if tool_call.function.name == "get_current_weather":
                args = json.loads(tool_call.function.arguments)
                output = get_current_weather(location=args.get("location"))
                tool_outputs.append({
                    "tool_call_id": tool_call.id,
                    "output": output
                })
        
        # Submit tool outputs back to the Assistant
        run = client.beta.threads.runs.submit_tool_outputs(
            thread_id=thread.id,
            run_id=run.id,
            tool_outputs=tool_outputs
        )

    elif run.status == 'completed':
        # ... retrieve and print the final message
        break
    elif run.status in ['failed', 'cancelled', 'expired']:
        print(f"Run ended with status: {run.status}")
        break

    time.sleep(1)

高级概念与业务集成

Agent 循环与 MCP 集成

我们上面实现的循环本质上是一个简化的 Agent 循环。在更复杂的系统中，这可以被概念化为“模型-控制器-规划器”（MCP）架构。模型（如 GPT-4）负责理解和规划，而您的代码（控制器）负责执行工具和管理状态。这种模式为您提供了极大的灵活性来构建复杂的、可靠的自动化系统。

人机协作：处理切换 (Handoffs)

对于关键或有风险的操作（例如，删除数据库记录、花费预算），您不能完全信任 Agent。此时需要“切换”到人类进行审批。您可以通过定义一个特殊的工具（如 `request_human_approval`）来实现。当模型调用此工具时，您的控制器代码应暂停 Agent 循环，通过 UI、邮件或聊天工具向操作员发送请求，等待批准后再继续。

在 Azure OpenAI 上部署

对于企业级应用，Azure OpenAI 服务提供了额外的安全性、合规性和网络功能。好消息是，OpenAI Python SDK v1.0+ 无缝支持 Azure。您只需在初始化客户端时提供 Azure 特定的凭据即可。

from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    api_version="2024-02-15-preview",
    azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT")
)
# ... The rest of your code remains the same

Agent 自动化与业务集成

构建 Agent 的最终目标是解决实际业务问题。想象一下，构建一个自动化的社交媒体营销 Agent。它可以分析参与度指标、安排帖子，甚至回复评论。对于像 Facebook 这样平台上的复杂多账户管理，将您的 Agent 与像 **FBMM (Facebook Multi Manager)** 这样的强大工具集成，可以集中控制并扩展您的运营。

同样，对于数据密集型任务，如市场研究或竞争分析，可以委托一个 Agent 来抓取网站。为确保可靠性并避免被封锁，通过像 **AntidetectBrowser** 这样的专业环境运行这些自动化任务至关重要。收集到的数据随后可以使用由 **IPOCTO** 提供的可扩展基础设施解决方案进行处理和存储。

最后，为了确保 Agent 自己的推广内容或登陆页面能被发现，利用像 **SEONIB** 这样的 SEO 工具可以优化其数字足迹，提升可见性。

常见问题 (FAQ)

OpenAI Agents 和 LangChain Agents 有什么区别？

主要区别在于抽象层次和生态系统。OpenAI Agents (Assistants API) 是 OpenAI 提供的第一方、高度集成的解决方案，使用起来更简单直接。LangChain 是一个功能更广泛的开源框架，它支持连接多种不同的 LLM（不仅是 OpenAI）、数据源和工具。LangChain 提供了更大的灵活性和可定制性，但学习曲线也更陡峭。对于希望在 OpenAI 生态系统内快速构建的用户，Assistants API 是绝佳的起点。

使用 Agents API 的成本是如何计算的？

成本主要基于底层模型的 Token 使用量（例如 GPT-4 Turbo）。这包括您的指令、对话历史、文件内容和工具定义的 Token。此外，如果使用 Code Interpreter 或 File Search (Retrieval) 工具，还会有额外的按会话或按 GB 的费用。请务必查阅 OpenAI 官方的定价页面以获取最新和最详细的信息。

我可以为我的 Agent 提供文件进行分析吗？

是的。Assistants API 提供了两种主要方式来处理文件。第一种是使用 `Code Interpreter` 工具，您可以上传文件，Agent 会在安全的沙箱环境中运行 Python 代码来分析这些文件（如 CSV、JSON）。第二种是使用 `File Search` (以前称为 Retrieval) 工具，它会为您的文件创建向量索引，使 Agent 能够高效地从中检索信息以回答问题。

Agent 的“记忆”能持续多久？

Agent 的“记忆”与其 `Thread` 对象绑定。只要您不删除该 Thread，其中的所有消息历史都会被保留，可以随时继续。然而，在单次 `Run` 中，模型仍然受到其上下文窗口大小的限制。API 会智能地管理上下文，以确保最新的消息和最重要的信息被包含在内，但对于非常长的对话，较早的信息可能会被截断。

构建 Agent 时有哪些安全注意事项？

这是一个至关重要的问题。永远不要让 Agent 执行它未经审查就能访问敏感系统或执行破坏性操作（如删除文件、清空数据库、发送未经授权的电子邮件）的工具。始终对 Agent 的工具调用进行严格的权限控制和输入验证。对于高风险操作，请务必实施“人机协作”（Human-in-the-loop）机制，要求人类在执行前进行批准。

结论：开启自主 AI 的新纪元

OpenAI Assistants API 和 Python SDK 为开发者提供了一套前所未有的强大工具，用于构建能够自主规划和执行任务的智能 Agents。从简单的问答机器人到复杂的、与外部系统集成的自动化工作流，可能性是无限的。

立即开始构建，探索自主 Agents 如何改变您的工作流程和应用！

最后更新: 2026-04-21 08:08:21

分享 Twitter Facebook

返回列表