openai--openai-agents-python
wehub-resource-sync
29ba7cee8f
Tests / tests (3.14) (push) Has been cancelled
Tests / lint (push) Has been cancelled
Tests / typecheck (push) Has been cancelled
Tests / tests (3.10) (push) Has been cancelled
Tests / tests (3.11) (push) Has been cancelled
Tests / tests (3.12) (push) Has been cancelled
Tests / tests (3.13) (push) Has been cancelled
Tests / tests-windows (push) Has been cancelled
Tests / build-docs (push) Has been cancelled
156 行
7.3 KiB
Markdown
156 行
7.3 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/openai/openai-agents-python) · [上游 README](https://github.com/openai/openai-agents-python/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
# OpenAI Agents SDK [](https://pypi.org/project/openai-agents/)
|
||
|
||
OpenAI Agents SDK 是一款轻量而强大的框架，用于构建多智能体工作流。它与提供商无关（provider-agnostic），支持 OpenAI Responses 和 Chat Completions API，以及 100 多种其他 LLM。
|
||
|
||
<img src="https://cdn.openai.com/API/docs/images/orchestration.png" alt="Agents Tracing UI 图像" style="max-height: 803px;">
|
||
|
||
> [!NOTE]
|
||
> 在找 JavaScript/TypeScript 版本？请查看 [Agents SDK JS/TS](https://github.com/openai/openai-agents-js).
|
||
|
||
### 核心概念：
|
||
|
||
1. [**Agents**](https://openai.github.io/openai-agents-python/agents): 配置了指令、工具、防护栏（guardrails）和交接（handoffs）的 LLM
|
||
1. [**Sandbox Agents**](https://openai.github.io/openai-agents-python/sandbox_agents): 预配置为与容器协同工作的智能体，可在较长的时间跨度内执行任务。
|
||
1. **[Agents as tools](https://openai.github.io/openai-agents-python/tools/#agents-as-tools) / [Handoffs](https://openai.github.io/openai-agents-python/handoffs/)**: 将特定任务委派给其他智能体
|
||
1. [**Tools**](https://openai.github.io/openai-agents-python/tools/): 多种工具使智能体能够执行操作（函数、MCP、托管工具）
|
||
1. [**Guardrails**](https://openai.github.io/openai-agents-python/guardrails/): 可配置的安全检查，用于输入和输出验证
|
||
1. [**Human in the loop**](https://openai.github.io/openai-agents-python/human_in_the_loop/): 内置机制，可在智能体运行过程中引入人工参与
|
||
1. [**Sessions**](https://openai.github.io/openai-agents-python/sessions/): 跨智能体运行自动管理对话历史
|
||
1. [**Tracing**](https://openai.github.io/openai-agents-python/tracing/): 内置智能体运行追踪，便于查看、调试和优化工作流
|
||
1. [**Realtime Agents**](https://openai.github.io/openai-agents-python/realtime/quickstart/): 使用 `gpt-realtime-2.1` 构建功能完备的强大语音智能体
|
||
|
||
浏览 [examples](https://github.com/openai/openai-agents-python/tree/main/examples) 目录查看 SDK 的实际用法，并阅读我们的 [documentation](https://openai.github.io/openai-agents-python/) 了解更多详情。
|
||
|
||
## 快速开始
|
||
|
||
开始前，请先配置 Python 环境（需要 Python 3.10 或更高版本），然后安装 OpenAI Agents SDK 包。
|
||
|
||
### venv
|
||
|
||
```bash
|
||
python -m venv .venv
|
||
source .venv/bin/activate # On Windows: .venv\Scripts\activate
|
||
pip install openai-agents
|
||
```
|
||
|
||
如需语音支持，请使用可选的 `voice` 依赖组安装：`pip install 'openai-agents[voice]'`。如需 Redis 会话支持，请使用可选的 `redis` 依赖组安装：`pip install 'openai-agents[redis]'`。
|
||
|
||
### uv
|
||
|
||
如果你熟悉 [uv](https://docs.astral.sh/uv/), 安装该包会更加简便：
|
||
|
||
```bash
|
||
uv init
|
||
uv add openai-agents
|
||
```
|
||
|
||
如需语音支持，请使用可选的 `voice` 依赖组安装：`uv add 'openai-agents[voice]'`。如需 Redis 会话支持，请使用可选的 `redis` 依赖组安装：`uv add 'openai-agents[redis]'`。
|
||
|
||
## 运行你的第一个智能体
|
||
|
||
SDK 支持三种主要方式来运行智能体。在运行以下任一示例之前，请设置 `OPENAI_API_KEY` 环境变量。
|
||
|
||
### 运行沙盒智能体
|
||
|
||
当智能体需要检查文件、运行命令、应用补丁，或在较长任务中保持工作区状态时，请使用 [`SandboxAgent`](https://openai.github.io/openai-agents-python/sandbox_agents)。
|
||
|
||
```python
|
||
from agents import Runner
|
||
from agents.run import RunConfig
|
||
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
|
||
from agents.sandbox.entries import GitRepo
|
||
from agents.sandbox.sandboxes import UnixLocalSandboxClient
|
||
|
||
agent = SandboxAgent(
|
||
name="Workspace Assistant",
|
||
instructions="Inspect the sandbox workspace before answering.",
|
||
default_manifest=Manifest(entries={"repo": GitRepo(repo="openai/openai-agents-python", ref="main")}),
|
||
)
|
||
|
||
result = Runner.run_sync(
|
||
agent,
|
||
"Inspect the repo README and summarize what this project does.",
|
||
run_config=RunConfig(sandbox=SandboxRunConfig(client=UnixLocalSandboxClient())),
|
||
)
|
||
print(result.final_output)
|
||
```
|
||
|
||
### 运行文本智能体
|
||
|
||
对于不需要持久实时连接或沙盒工作区的工作流，请使用文本 `Agent`。
|
||
|
||
```python
|
||
from agents import Agent, Runner
|
||
|
||
agent = Agent(name="Assistant", instructions="You are a helpful assistant")
|
||
|
||
result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
|
||
print(result.final_output)
|
||
|
||
# Code within the code,
|
||
# Functions calling themselves,
|
||
# Infinite loop's dance.
|
||
```
|
||
|
||
（_Jupyter notebook 用户请参阅 [hello_world_jupyter.ipynb](https://github.com/openai/openai-agents-python/blob/main/examples/basic/hello_world_jupyter.ipynb)_)
|
||
|
||
### 运行实时智能体
|
||
|
||
通过 WebSocket 实现低延迟、服务端语音与多模态体验时，请使用 [`RealtimeAgent`](https://openai.github.io/openai-agents-python/realtime/quickstart/)。
|
||
|
||
```python
|
||
import asyncio
|
||
from agents.realtime import RealtimeAgent, RealtimeRunner
|
||
|
||
async def main() -> None:
|
||
agent = RealtimeAgent(name="Assistant", instructions="You are a helpful voice assistant. Keep responses short.")
|
||
runner = RealtimeRunner(starting_agent=agent)
|
||
session = await runner.run()
|
||
|
||
async with session:
|
||
await session.send_message("Say hello in one short sentence.")
|
||
async for event in session:
|
||
if event.type == "audio":
|
||
# Forward or play event.audio.data.
|
||
pass
|
||
elif event.type == "history_added":
|
||
print(event.item)
|
||
elif event.type == "agent_end":
|
||
break
|
||
|
||
if __name__ == "__main__":
|
||
asyncio.run(main())
|
||
```
|
||
|
||
浏览 [examples](https://github.com/openai/openai-agents-python/tree/main/examples) 目录查看 SDK 的实际用法，并阅读我们的 [documentation](https://openai.github.io/openai-agents-python/) 了解更多详情。
|
||
|
||
## 致谢
|
||
|
||
我们要感谢开源社区的杰出贡献，尤其是：
|
||
|
||
- [Pydantic](https://docs.pydantic.dev/latest/)
|
||
- [Requests](https://github.com/psf/requests)
|
||
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
|
||
- [Griffe](https://github.com/mkdocstrings/griffe)
|
||
|
||
本库包含以下可选依赖：
|
||
|
||
- [websockets](https://github.com/python-websockets/websockets)
|
||
- [SQLAlchemy](https://github.com/sqlalchemy/sqlalchemy)
|
||
- [any-llm](https://github.com/mozilla-ai/any-llm) and [LiteLLM](https://github.com/BerriAI/litellm)
|
||
|
||
我们还依赖以下工具来管理项目：
|
||
|
||
- [uv](https://github.com/astral-sh/uv) and [ruff](https://github.com/astral-sh/ruff)
|
||
- [mypy](https://github.com/python/mypy) and [Pyright](https://github.com/microsoft/pyright)
|
||
- [pytest](https://github.com/pytest-dev/pytest) and [Coverage.py](https://github.com/coveragepy/coveragepy)
|
||
- [MkDocs](https://github.com/squidfunk/mkdocs-material)
|
||
|
||
我们致力于持续将 Agents SDK 构建为开源框架，以便社区中的其他人能够在我们的方法基础上进行扩展。
|