docs: improve the consistency of docs
This commit is contained in:
Kazuhiro Sera
@@ -10,14 +10,15 @@ The OpenAI Agents SDK is a lightweight yet powerful framework for building multi
|
||||
### 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. [**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. [**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. [**Voice agents**](https://openai.github.io/openai-agents-python/voice/quickstart/): Build voice pipelines that combine speech-to-text, an agent workflow, and text-to-speech
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
@@ -48,7 +49,26 @@ For voice support, install with the optional `voice` group: `uv add 'openai-agen
|
||||
|
||||
## 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.
|
||||
The SDK supports four primary ways to run agents. Set the `OPENAI_API_KEY` environment variable before running any of these examples.
|
||||
|
||||
### Run a text agent
|
||||
|
||||
Use a text `Agent` for workflows that do not need a persistent realtime connection or a sandbox workspace.
|
||||
|
||||
```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.
|
||||
```
|
||||
|
||||
(_For Jupyter notebook users, see [hello_world_jupyter.ipynb](https://github.com/openai/openai-agents-python/blob/main/examples/basic/hello_world_jupyter.ipynb)_)
|
||||
|
||||
### Run a sandbox agent
|
||||
|
||||
@@ -77,25 +97,6 @@ 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.
|
||||
|
||||
```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.
|
||||
```
|
||||
|
||||
(_For Jupyter notebook users, see [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.
|
||||
@@ -124,6 +125,35 @@ if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
### Run a voice agent
|
||||
|
||||
Use a [`VoicePipeline`](https://openai.github.io/openai-agents-python/voice/quickstart/) to turn audio into text, run an agent workflow, and stream generated speech.
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
|
||||
import numpy as np
|
||||
|
||||
from agents import Agent
|
||||
from agents.voice import AudioInput, SingleAgentVoiceWorkflow, VoicePipeline
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
agent = Agent(name="Assistant", instructions="You are a helpful voice assistant.")
|
||||
pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent))
|
||||
audio_input = AudioInput(buffer=np.zeros(24000 * 3, dtype=np.int16))
|
||||
|
||||
result = await pipeline.run(audio_input)
|
||||
async for event in result.stream():
|
||||
if event.type == "voice_stream_event_audio":
|
||||
# Forward or play event.data.
|
||||
pass
|
||||
|
||||
|
||||
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.
|
||||
|
||||
## Acknowledgements
|
||||
|
||||
+4
-3
@@ -17,17 +17,18 @@ The SDK has two driving design principles:
|
||||
|
||||
Here are the main features of the SDK:
|
||||
|
||||
- **Agent loop**: A built-in agent loop that handles tool invocation, sends results back to the LLM, and continues until the task is complete.
|
||||
- **Agents**: Build agents with instructions, tools, guardrails, handoffs, and a built-in loop that continues until the task is complete.
|
||||
- **Sandbox agents**: Run specialists inside real isolated workspaces with manifest-defined files, sandbox client choice, and resumable sandbox sessions.
|
||||
- **Realtime agents**: Build powerful voice agents with `gpt-realtime-2.1`, automatic interruption detection, context management, guardrails, and more.
|
||||
- **Voice agents**: Build voice pipelines that combine speech-to-text, an agent workflow, and text-to-speech.
|
||||
- **Python-first**: Use built-in language features to orchestrate and chain agents, rather than needing to learn new abstractions.
|
||||
- **Agents as tools / Handoffs**: A powerful mechanism for coordinating and delegating work across multiple agents.
|
||||
- **Sandbox agents**: Run specialists inside real isolated workspaces with manifest-defined files, sandbox client choice, and resumable sandbox sessions.
|
||||
- **Guardrails**: Run input validation and safety checks in parallel with agent execution, and fail fast when checks do not pass.
|
||||
- **Function tools**: Turn any Python function into a tool with automatic schema generation and Pydantic-powered validation.
|
||||
- **MCP server tool calling**: Built-in MCP server tool integration that works the same way as function tools.
|
||||
- **Sessions**: A persistent memory layer for maintaining working context within an agent loop.
|
||||
- **Human in the loop**: Built-in mechanisms for involving humans across agent runs.
|
||||
- **Tracing**: Built-in tracing for visualizing, debugging, and monitoring workflows, with support for the OpenAI suite of evaluation, fine-tuning, and distillation tools.
|
||||
- **Realtime Agents**: Build powerful voice agents with `gpt-realtime-2.1`, automatic interruption detection, context management, guardrails, and more.
|
||||
|
||||
## Agents SDK or Responses API?
|
||||
|
||||
|
||||
+29
-29
@@ -59,6 +59,14 @@ plugins:
|
||||
- Concepts: sandbox/guide.md
|
||||
- Sandbox clients: sandbox/clients.md
|
||||
- Agent memory: sandbox/memory.md
|
||||
- Realtime agents:
|
||||
- Quickstart: realtime/quickstart.md
|
||||
- Transport: realtime/transport.md
|
||||
- Guide: realtime/guide.md
|
||||
- Voice agents:
|
||||
- Quickstart: voice/quickstart.md
|
||||
- Pipeline: voice/pipeline.md
|
||||
- Tracing: voice/tracing.md
|
||||
- Models: models/index.md
|
||||
- Tools: tools.md
|
||||
- Guardrails: guardrails.md
|
||||
@@ -77,14 +85,6 @@ plugins:
|
||||
- Usage: usage.md
|
||||
- Model context protocol (MCP): mcp.md
|
||||
- Tracing: tracing.md
|
||||
- Realtime agents:
|
||||
- Quickstart: realtime/quickstart.md
|
||||
- Transport: realtime/transport.md
|
||||
- Guide: realtime/guide.md
|
||||
- Voice agents:
|
||||
- Quickstart: voice/quickstart.md
|
||||
- Pipeline: voice/pipeline.md
|
||||
- Tracing: voice/tracing.md
|
||||
- Agent visualization: visualization.md
|
||||
- REPL utility: repl.md
|
||||
- Examples: examples.md
|
||||
@@ -209,6 +209,13 @@ plugins:
|
||||
- 概念: sandbox/guide.md
|
||||
- Sandbox クライアント: sandbox/clients.md
|
||||
- エージェントメモリ: sandbox/memory.md
|
||||
- リアルタイムエージェント:
|
||||
- realtime/quickstart.md
|
||||
- realtime/guide.md
|
||||
- 音声エージェント:
|
||||
- voice/quickstart.md
|
||||
- voice/pipeline.md
|
||||
- voice/tracing.md
|
||||
- モデル: models/index.md
|
||||
- tools.md
|
||||
- guardrails.md
|
||||
@@ -227,13 +234,6 @@ plugins:
|
||||
- usage.md
|
||||
- mcp.md
|
||||
- tracing.md
|
||||
- リアルタイムエージェント:
|
||||
- realtime/quickstart.md
|
||||
- realtime/guide.md
|
||||
- 音声エージェント:
|
||||
- voice/quickstart.md
|
||||
- voice/pipeline.md
|
||||
- voice/tracing.md
|
||||
- visualization.md
|
||||
- repl.md
|
||||
- コード例: examples.md
|
||||
@@ -252,6 +252,13 @@ plugins:
|
||||
- 개념: sandbox/guide.md
|
||||
- 샌드박스 클라이언트: sandbox/clients.md
|
||||
- 에이전트 메모리: sandbox/memory.md
|
||||
- 실시간 에이전트:
|
||||
- realtime/quickstart.md
|
||||
- realtime/guide.md
|
||||
- 음성 에이전트:
|
||||
- voice/quickstart.md
|
||||
- voice/pipeline.md
|
||||
- voice/tracing.md
|
||||
- 모델: models/index.md
|
||||
- tools.md
|
||||
- guardrails.md
|
||||
@@ -270,13 +277,6 @@ plugins:
|
||||
- usage.md
|
||||
- mcp.md
|
||||
- tracing.md
|
||||
- 실시간 에이전트:
|
||||
- realtime/quickstart.md
|
||||
- realtime/guide.md
|
||||
- 음성 에이전트:
|
||||
- voice/quickstart.md
|
||||
- voice/pipeline.md
|
||||
- voice/tracing.md
|
||||
- visualization.md
|
||||
- repl.md
|
||||
- 코드 예제: examples.md
|
||||
@@ -295,6 +295,13 @@ plugins:
|
||||
- 概念: sandbox/guide.md
|
||||
- 沙箱客户端: sandbox/clients.md
|
||||
- 智能体记忆: sandbox/memory.md
|
||||
- 实时智能体:
|
||||
- realtime/quickstart.md
|
||||
- realtime/guide.md
|
||||
- 语音智能体:
|
||||
- voice/quickstart.md
|
||||
- voice/pipeline.md
|
||||
- voice/tracing.md
|
||||
- 模型: models/index.md
|
||||
- tools.md
|
||||
- guardrails.md
|
||||
@@ -313,13 +320,6 @@ plugins:
|
||||
- usage.md
|
||||
- mcp.md
|
||||
- tracing.md
|
||||
- 实时智能体:
|
||||
- realtime/quickstart.md
|
||||
- realtime/guide.md
|
||||
- 语音智能体:
|
||||
- voice/quickstart.md
|
||||
- voice/pipeline.md
|
||||
- voice/tracing.md
|
||||
- visualization.md
|
||||
- repl.md
|
||||
- 示例: examples.md
|
||||
|
||||
Reference in New Issue
Block a user