diff --git a/README.md b/README.md index a8acfe5..84c729e 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,35 @@ + +> [!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 [![PyPI](https://img.shields.io/pypi/v/openai-agents?label=pypi%20package)](https://pypi.org/project/openai-agents/) -The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows. It is provider-agnostic, supporting the OpenAI Responses and Chat Completions APIs, as well as 100+ other LLMs. +OpenAI Agents SDK 是一款轻量而强大的框架，用于构建多智能体工作流。它与提供商无关（provider-agnostic），支持 OpenAI Responses 和 Chat Completions API，以及 100 多种其他 LLM。 -Image of the Agents Tracing UI +Agents Tracing UI 图像 > [!NOTE] -> Looking for the JavaScript/TypeScript version? Check out [Agents SDK JS/TS](https://github.com/openai/openai-agents-js). +> 在找 JavaScript/TypeScript 版本？请查看 [Agents SDK JS/TS](https://github.com/openai/openai-agents-js). -### Core concepts: +### 核心概念： -1. [**Agents**](https://openai.github.io/openai-agents-python/agents): LLMs configured with instructions, tools, guardrails, and handoffs -1. [**Sandbox Agents**](https://openai.github.io/openai-agents-python/sandbox_agents): Agents preconfigured to work with a container to perform work over long time horizons. -1. **[Agents as tools](https://openai.github.io/openai-agents-python/tools/#agents-as-tools) / [Handoffs](https://openai.github.io/openai-agents-python/handoffs/)**: Delegating to other agents for specific tasks -1. [**Tools**](https://openai.github.io/openai-agents-python/tools/): Various Tools let agents take actions (functions, MCP, hosted tools) -1. [**Guardrails**](https://openai.github.io/openai-agents-python/guardrails/): Configurable safety checks for input and output validation -1. [**Human in the loop**](https://openai.github.io/openai-agents-python/human_in_the_loop/): Built-in mechanisms for involving humans across agent runs -1. [**Sessions**](https://openai.github.io/openai-agents-python/sessions/): Automatic conversation history management across agent runs -1. [**Tracing**](https://openai.github.io/openai-agents-python/tracing/): Built-in tracking of agent runs, allowing you to view, debug and optimize your workflows -1. [**Realtime Agents**](https://openai.github.io/openai-agents-python/realtime/quickstart/): Build powerful voice agents with `gpt-realtime-2.1` and full agent features +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` 构建功能完备的强大语音智能体 -Explore the [examples](https://github.com/openai/openai-agents-python/tree/main/examples) directory to see the SDK in action, and read our [documentation](https://openai.github.io/openai-agents-python/) for more details. +浏览 [examples](https://github.com/openai/openai-agents-python/tree/main/examples) 目录查看 SDK 的实际用法，并阅读我们的 [documentation](https://openai.github.io/openai-agents-python/) 了解更多详情。 -## Get started +## 快速开始 -To get started, set up your Python environment (Python 3.10 or newer required), and then install OpenAI Agents SDK package. +开始前，请先配置 Python 环境（需要 Python 3.10 或更高版本），然后安装 OpenAI Agents SDK 包。 ### venv @@ -33,26 +39,26 @@ source .venv/bin/activate # On Windows: .venv\Scripts\activate pip install openai-agents ``` -For voice support, install with the optional `voice` group: `pip install 'openai-agents[voice]'`. For Redis session support, install with the optional `redis` group: `pip install 'openai-agents[redis]'`. +如需语音支持，请使用可选的 `voice` 依赖组安装：`pip install 'openai-agents[voice]'`。如需 Redis 会话支持，请使用可选的 `redis` 依赖组安装：`pip install 'openai-agents[redis]'`。 ### uv -If you're familiar with [uv](https://docs.astral.sh/uv/), installing the package would be even easier: +如果你熟悉 [uv](https://docs.astral.sh/uv/), 安装该包会更加简便： ```bash uv init uv add openai-agents ``` -For voice support, install with the optional `voice` group: `uv add 'openai-agents[voice]'`. For Redis session support, install with the optional `redis` group: `uv add 'openai-agents[redis]'`. +如需语音支持，请使用可选的 `voice` 依赖组安装：`uv add 'openai-agents[voice]'`。如需 Redis 会话支持，请使用可选的 `redis` 依赖组安装：`uv add 'openai-agents[redis]'`。 -## Run your first agents +## 运行你的第一个智能体 -The SDK supports three primary ways to run agents. Set the `OPENAI_API_KEY` environment variable before running any of these examples. +SDK 支持三种主要方式来运行智能体。在运行以下任一示例之前，请设置 `OPENAI_API_KEY` 环境变量。 -### Run a sandbox agent +### 运行沙盒智能体 -Use a [`SandboxAgent`](https://openai.github.io/openai-agents-python/sandbox_agents) when the agent needs to inspect files, run commands, apply patches, or preserve workspace state across longer tasks. +当智能体需要检查文件、运行命令、应用补丁，或在较长任务中保持工作区状态时，请使用 [`SandboxAgent`](https://openai.github.io/openai-agents-python/sandbox_agents)。 ```python from agents import Runner @@ -75,9 +81,9 @@ result = Runner.run_sync( print(result.final_output) ``` -### Run a text agent +### 运行文本智能体 -Use a text `Agent` for workflows that do not need a persistent realtime connection or a sandbox workspace. +对于不需要持久实时连接或沙盒工作区的工作流，请使用文本 `Agent`。 ```python from agents import Agent, Runner @@ -92,11 +98,11 @@ print(result.final_output) # Infinite loop's dance. ``` -(_For Jupyter notebook users, see [hello_world_jupyter.ipynb](https://github.com/openai/openai-agents-python/blob/main/examples/basic/hello_world_jupyter.ipynb)_) +（_Jupyter notebook 用户请参阅 [hello_world_jupyter.ipynb](https://github.com/openai/openai-agents-python/blob/main/examples/basic/hello_world_jupyter.ipynb)_) -### Run a realtime agent +### 运行实时智能体 -Use a [`RealtimeAgent`](https://openai.github.io/openai-agents-python/realtime/quickstart/) for low-latency, server-side voice and multimodal experiences over WebSocket. +通过 WebSocket 实现低延迟、服务端语音与多模态体验时，请使用 [`RealtimeAgent`](https://openai.github.io/openai-agents-python/realtime/quickstart/)。 ```python import asyncio @@ -122,28 +128,28 @@ if __name__ == "__main__": asyncio.run(main()) ``` -Explore the [examples](https://github.com/openai/openai-agents-python/tree/main/examples) directory to see the SDK in action, and read our [documentation](https://openai.github.io/openai-agents-python/) for more details. +浏览 [examples](https://github.com/openai/openai-agents-python/tree/main/examples) 目录查看 SDK 的实际用法，并阅读我们的 [documentation](https://openai.github.io/openai-agents-python/) 了解更多详情。 -## Acknowledgements +## 致谢 -We'd like to acknowledge the excellent work of the open-source community, especially: +我们要感谢开源社区的杰出贡献，尤其是： - [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) -This library has these optional dependencies: +本库包含以下可选依赖： - [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) -We also rely on the following tools to manage the project: +我们还依赖以下工具来管理项目： - [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) -We're committed to continuing to build the Agents SDK as an open source framework so others in the community can expand on our approach. +我们致力于持续将 Agents SDK 构建为开源框架，以便社区中的其他人能够在我们的方法基础上进行扩展。