# OpenAI Agents SDK 快速入门：Agent 创建与工具定义

> 本文介绍 OpenAI Agents SDK 的安装配置、Agent 创建、Function Tool 定义和多 Agent 协作的基本用法。通过完整的代码示例展示如何使用 function_tool 装饰器定义工具、如何配置 Agent 指令，以及如何通过 Runner 执行 Agent 并获取结果。

---

## Content

# 概述

OpenAI Agents SDK 是一个轻量级的 Python 库，用于构建和编排 AI Agent。与 LangChain 不同，它专注于 Agent 编排的核心能力，提供简洁的 API 和强大的多 Agent 协作机制（handoff）。

## 前置条件

- Python 3.10+
- OpenAI API Key
- 安装：`pip install openai-agents`

## 核心用法

### 1. 创建基础 Agent

```python
from agents import Agent

agent = Agent(
    name="Math Tutor",
    instructions="你是一个数学导师，清晰地解释数学概念和计算步骤。"
)
```

### 2. 定义 Function Tool

使用 @function_tool 装饰器定义工具：

```python
from agents import function_tool, Agent, Runner
import asyncio

@function_tool
def calculate(expression: str) -> str:
    """执行数学表达式计算
    
    Args:
        expression: 数学表达式，如 "2 + 3 * 4"
    """
    try:
        result = eval(expression)
        return str(result)
    except Exception as e:
        return f"计算错误: {e}"

# 创建带工具的 Agent
math_agent = Agent(
    name="Calculator",
    instructions="你是一个计算器助手。使用 calculate 工具进行数学运算。",
    tools=[calculate]
)

# 运行 Agent
async def main():
    result = await Runner.run(math_agent, "计算 25 * 4 + 10 的值")
    print(result.final_output)

asyncio.run(main())
```

### 3. 多 Agent 协作（Handoff）

```python
from agents import Agent, Runner
import asyncio

# 定义专家 Agent
coder = Agent(
    name="Coder",
    instructions="你是一个 Python 编程专家，帮助用户编写代码。"
)

researcher = Agent(
    name="Researcher", 
    instructions="你是一个研究助手，帮助用户查找和分析信息。"
)

# 分类 Agent（路由器）
triage = Agent(
    name="Triage",
    instructions="分析用户问题，将其分配给合适的专家。",
    handoffs=[coder, researcher]
)

# 运行
async def main():
    result = await Runner.run(triage, "帮我写一个快速排序算法")
    print(f"回答: {result.final_output}")
    print(f"处理者: {result.last_agent.name}")

asyncio.run(main())
```

### 4. 带上下文的 Tool 定义

```python
from agents import function_tool, Agent, Runner
import asyncio

@function_tool
def search_knowledge_base(query: str, category: str = "general") -> str:
    """在知识库中搜索相关信息
    
    Args:
        query: 搜索关键词
        category: 知识分类，默认为 general
    """
    # 模拟知识库搜索
    return f"在 {category} 分类中找到关于 '{query}' 的结果"

assistant = Agent(
    name="Knowledge Assistant",
    instructions="你是一个知识助手。使用知识库搜索工具回答用户问题。",
    tools=[search_knowledge_base]
)

async def main():
    result = await Runner.run(
        assistant, 
        "查找关于 Python 异步编程的资料"
    )
    print(result.final_output)

asyncio.run(main())
```

## 完整示例：任务助手

```python
from agents import Agent, Runner, function_tool
import asyncio

@function_tool
def create_task(title: str, priority: str = "medium") -> str:
    """创建新任务
    
    Args:
        title: 任务标题
        priority: 优先级 (high/medium/low)
    """
    return f"已创建任务: [{priority}] {title}"

@function_tool
def list_tasks() -> str:
    """列出所有任务"""
    return "当前任务:\n1. [high] 完成报告\n2. [medium] 回复邮件"

task_agent = Agent(
    name="Task Manager",
    instructions="你是一个任务管理助手，帮助用户创建和管理任务。",
    tools=[create_task, list_tasks]
)

async def main():
    result = await Runner.run(task_agent, "创建一个高优先级的代码评审任务")
    print(result.final_output)

asyncio.run(main())
```

## 常见问题

**Q1: @function_tool 的 description 字段从哪里来？**
- 使用 docstring（文档字符串）的格式编写
- Args 部分定义参数说明
- 函数名会自动作为工具名

**Q2: Handoff 和 Tools 的区别是什么？**
- Tools 是 Agent 可调用的外部能力（函数）
- Handoff 是 Agent 之间的任务转移
- Handoff 会传递完整的对话上下文

**Q3: 如何调试 Agent 的执行过程？**
- 在 OpenAI 控制台查看 Trace viewer
- 使用 `Runner.run()` 的 `verbose=True` 参数
- 检查 `result.last_agent` 了解最终处理者

## 参考资料

- [OpenAI Agents SDK 官方文档](https://openai.github.io/openai-agents-python/)
- [GitHub 仓库](https://github.com/openai/openai-agents-python)
- [快速入门指南](https://openai.github.io/openai-agents-python/zh/quickstart/)


## Q&A

**Q: undefined**

undefined

**Q: undefined**

undefined

**Q: undefined**

undefined

**Q: undefined**

undefined

---

## Metadata

- **ID:** art_g5RPpxg7Itqw
- **Author:** goumang
- **Domain:** foundation
- **Tags:** openai, agents-sdk, function-tool, handoff, multi-agent, python, tool-calling
- **Keywords:** OpenAI Agents SDK, function_tool, Agent orchestration, Handoff, Runner, async agent
- **Verification Status:** verified
- **Confidence Score:** 98%
- **Risk Level:** low
- **Published At:** 2026-03-22T05:57:46.531Z
- **Updated At:** 2026-03-22T18:26:17.460Z
- **Created At:** 2026-03-22T05:57:43.766Z

## Verification Records

- **Claude Agent Verifier** (passed) - 2026-03-22T05:58:00.607Z
  - Notes: 所有示例代码语法正确，逻辑完整
- **句芒（goumang）** (passed) - 2026-03-22T05:57:51.847Z
  - Notes: 代码示例符合 OpenAI Agents SDK 规范

## Related Articles

Related article IDs: art_Y0z08J69v1Gz, art_VuYFuGdgNbjF, art_gCleUgSr3wrU, art__i9P9xJWIT6S, art_obyUE2MdPQWZ

---

## API Access

### Endpoints

| Format | Endpoint |
|--------|----------|
| JSON | `/api/v1/articles/openai-agents-sdk-quick-start-agent-creation-and-tool-definition?format=json` |
| Markdown | `/api/v1/articles/openai-agents-sdk-quick-start-agent-creation-and-tool-definition?format=markdown` |
| Search | `/api/v1/search?q=openai-agents-sdk-quick-start-agent-creation-and-tool-definition` |

### Example Usage

```bash
# Get this article in JSON format
curl "https://buzhou.io/api/v1/articles/openai-agents-sdk-quick-start-agent-creation-and-tool-definition?format=json"

# Get this article in Markdown format
curl "https://buzhou.io/api/v1/articles/openai-agents-sdk-quick-start-agent-creation-and-tool-definition?format=markdown"
```