> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# OpenAI Agents with PraisonAI
> Run the OpenAI Agents SDK through PraisonAI's YAML and CLI, including agent handoffs
`framework: openai_agents` runs your agents YAML through the official OpenAI Agents SDK, with handoffs and task chaining from a single install.
Need a framework that isn't listed here? See [Framework Adapter Plugins](/docs/features/framework-adapter-plugins) to register your own via Python entry points.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "OpenAI Agents Framework"
YAML[📄 YAML Config] --> Adapter[🔌 OpenAIAgentsAdapter]
Adapter --> SDK[🤖 OpenAI Agents SDK]
SDK --> Handoff[🔀 Handoffs]
SDK --> Result[✅ Result]
end
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class YAML input
class Adapter,SDK process
class Handoff agent
class Result output
```
## Quick Start
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install "praisonai[openai-agents]"
# pulls praisonai-frameworks[openai-agents]>=0.1.3 transitively
```
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
framework: openai_agents
topic: Simple Question Answer
roles:
researcher:
role: Helper
goal: Answer simple questions accurately
backstory: I am a helpful assistant
tasks:
answer:
description: What is the capital of France? Reply with just the city name.
expected_output: Paris
```
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export OPENAI_API_KEY=your-key
praisonai agents.yaml --framework openai_agents
```
Pass `--framework openai_agents` on the CLI **or** set `framework: openai_agents` in your YAML — either alone is enough.
***
## How OpenAI Agents Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant PraisonAI
participant Registry as FrameworkAdapterRegistry
participant Adapter as OpenAIAgentsAdapter
participant SDK as OpenAI Agents SDK
User->>PraisonAI: praisonai agents.yaml --framework openai_agents
PraisonAI->>Registry: create("openai_agents")
Registry-->>PraisonAI: OpenAIAgentsAdapter (entry-point)
PraisonAI->>Adapter: run(config, llm_config, topic, tools_dict)
Adapter->>SDK: build agents + tasks (+ handoffs)
SDK->>SDK: execute task graph
SDK-->>Adapter: result text
Adapter-->>PraisonAI: "### OpenAI Agents Output ###\n..."
PraisonAI-->>User: result
```
Every result begins with the sentinel prefix `### OpenAI Agents Output ###`. Downstream parsers can split on this to extract only the run output.
***
## Sequential Context (Task Chaining)
Tasks reference outputs of earlier tasks with `context: [task_name]`:
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
framework: openai_agents
topic: text processing
roles:
writer:
role: Writer
goal: Transform text
backstory: Professional writer
tasks:
draft:
description: Write one word hello
expected_output: hello
polish:
description: Uppercase the prior draft word only.
expected_output: HELLO
context:
- draft
```
The `context:` semantics match other framework wrappers (CrewAI, LangGraph, Google ADK). The OpenAI Agents adapter wires the dependency list into the SDK task graph.
***
## Agent Handoffs via YAML
`framework: openai_agents` is one of three runtimes with first-class handoff support (alongside `praisonai` and `autogen_v4` — confirmed by `praisonai doctor`).
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
framework: openai_agents
topic: greeting
roles:
triage:
role: Triage Agent
goal: Route English requests to English Agent
backstory: Delegate English to the English Agent.
handoff:
to:
- English Agent
tasks:
route:
description: User says hello in English. Delegate appropriately.
expected_output: A friendly English reply
english:
role: English Agent
goal: Reply in English only
backstory: English specialist.
```
`handoff.to` lists target agents by their `role:` value (here `"English Agent"`), not the YAML role key. Spaced role names such as `Triage Agent` are sanitised for internal task references, so human-readable labels stay in YAML.
See [Agent Handoffs](/docs/features/handoffs) for the delegation model and [Handoff Tool Policy](/docs/features/handoff-tool-policy) for the tool-intersection rule applied on top of the SDK handoff mechanism.
`framework: openai_agents` is only valid in **agents YAML** with a `roles:` block. Using it in Workflow YAML (steps-style) raises `ValueError: framework='openai_agents' in workflow YAML is not supported for workflow execution` at load time.
***
## Verify Installation
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai doctor
```
When `praisonai[openai-agents]` is installed, the runtime table includes **OpenAI Agents SDK** with capabilities such as `agent_creation`, `tool_execution`, and optional `handoff_support`.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai._framework_availability import is_available
if is_available("openai_agents"):
print("OpenAI Agents SDK is installed and importable")
```
The probe checks, in order: the `openai-agents` distribution is installed, the `agents` import namespace exists, and `from agents import Runner` succeeds.
***
## Pip Extras
| Extra | Installs | Required for |
| ------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------- |
| `praisonai[openai-agents]` | `praisonai-frameworks[openai-agents]>=0.1.3`, `praisonai-tools>=0.1.0` | Doctor recognition and CLI/YAML dispatch |
| `praisonai-frameworks[openai-agents]` | Adapter entry point + OpenAI Agents PyPI package | Executing `framework: openai_agents` |
The YAML/CLI key is `openai_agents` (underscore). Install hints use `openai-agents` (hyphen) to match PyPI normalisation.
***
## Advanced — Direct Adapter Use
Most users should use the CLI/YAML flow above. To call the adapter directly:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import os
from praisonai_frameworks.openai_agents.adapter import OpenAIAgentsAdapter
config = {
"framework": "openai_agents",
"topic": "Quick test",
"roles": {
"helper": {
"role": "Assistant",
"goal": "Answer briefly",
"backstory": "Helpful assistant",
"tasks": {
"answer": {
"description": "Reply with exactly the word OK.",
"expected_output": "OK",
}
},
}
},
}
llm_config = [{"model": "gpt-4o-mini", "api_key": os.environ["OPENAI_API_KEY"]}]
result = OpenAIAgentsAdapter().run(config, llm_config, "Quick test", tools_dict={})
assert "### OpenAI Agents Output ###" in result
```
***
## Troubleshooting
| Symptom | Fix |
| ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| `Framework 'openai_agents' was requested but is not installed` | `pip install "praisonai[openai-agents]"` or `pip install 'praisonai-frameworks[openai-agents]'` |
| `ValueError: framework='openai_agents' in workflow YAML is not supported for workflow execution` | Switch to agents YAML with `roles:` — not steps-style Workflow YAML |
| `framework='openai_agents' is not a valid choice` (older CLI) | Upgrade PraisonAI or set `framework: openai_agents` in YAML and omit `--framework` |
| Handoff target not found | Ensure `handoff.to` strings match another role's `role:` field exactly |
***
## Best Practices
Use the `roles:` agents.yaml shape. The native Workflow YAML engine supports only `framework: praisonai`.
Declare dependencies with `context: [prior_task]` instead of imperative wiring — the adapter builds the SDK task graph for you.
Choose this framework when you want the official OpenAI Agents SDK semantics, especially SDK-native handoffs, rather than PraisonAI-native orchestration.
Split results on `### OpenAI Agents Output ###` when you need only the model text in downstream automation.
***
## Related
AutoGen family wrapper
CrewAI wrapper
Native PraisonAI runtime
Delegation model and Python API
Tool intersection on handoff
Probe API and install hints