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.

Diagram

Quick Start

Install

bash

pip install "praisonai[openai-agents]"
# pulls praisonai-frameworks[openai-agents]>=0.1.3 transitively

Create agents.yaml

yaml

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

Run

bash

export OPENAI_API_KEY=your-key
praisonai agents.yaml --framework openai_agents

How OpenAI Agents Works

Diagram

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

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

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

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.

Verify Installation

bash

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

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`

Advanced — Direct Adapter Use

Most users should use the CLI/YAML flow above. To call the adapter directly:

python

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

Prefer agents YAML with roles

Use the roles: agents.yaml shape. The native Workflow YAML engine supports only framework: praisonai.

Use context for task dependencies

Declare dependencies with context: [prior_task] instead of imperative wiring — the adapter builds the SDK task graph for you.

When to pick openai_agents

Choose this framework when you want the official OpenAI Agents SDK semantics, especially SDK-native handoffs, rather than PraisonAI-native orchestration.

Parse on the output sentinel

Split results on ### OpenAI Agents Output ### when you need only the model text in downstream automation.

AutoGen

AutoGen family wrapper

CrewAI

CrewAI wrapper

PraisonAI Agents

Native PraisonAI runtime

Agent Handoffs

Delegation model and Python API

Handoff Tool Policy

Tool intersection on handoff