feat: Add support for OpenAI Agents SDK

[NiveditJain]

Allow developers to use the OpenAI Agents SDK with Exosphere as the underlying reliability and orchestration platform.

# Goal: familiar OpenAI patterns, Exosphere reliability
from exospherehost.openai import agents

agent = agents.Agent(
 name="research-assistant",
 instructions="You help with research tasks",
 tools=[web_search, file_reader]
)

# Runs on Exosphere with retries, state persistence, observability
result = await agents.run(agent, "Find recent papers on LLM agents")

---

Why This Matters

Without Exosphere	With Exosphere
Agent crashes = lost progress	State persisted, resumable
No retry logic	Configurable retry policies
No observability	Full execution trace in dashboard
Single machine	Distributed across workers
Manual orchestration	Graph-based multi-agent workflows

---

OpenAI Agents SDK Overview

The OpenAI Agents SDK provides:

• Agents: LLM + instructions + tools
• Tools: Functions the agent can call
• Handoffs: Agent-to-agent delegation
• Guardrails: Input/output validation
• Tracing: Execution visibility

# Standard OpenAI Agents SDK usage
from agents import Agent, Runner

agent = Agent(
 name="assistant",
 instructions="You are helpful",
 tools=[my_tool]
)

result = Runner.run_sync(agent, "Hello")

---

Proposed Integration

Approach: Wrap OpenAI SDK, Execute on Exosphere

flowchart TB
 subgraph "Developer Code"
 DEV[from exospherehost.openai import agents]
 end
 
 subgraph "exospherehost.openai"
 WRAP[Thin wrapper over OpenAI SDK]
 end
 
 subgraph "Exosphere Runtime"
 NODE[AgentNode executes agent]
 SM[State Manager tracks progress]
 end
 
 DEV --> WRAP
 WRAP --> NODE
 NODE --> SM

Loading

Key Design Decisions

1. Minimal wrapper: Don't reimplement OpenAI SDK, wrap it
2. Transparent to developers: Same API they already know
3. Opt-in reliability: Easy to add retries, persistence
4. Graph integration: Agents as nodes in larger workflows

---

Prototype Scope

In Scope

• exospherehost.openai.agents module
• Wrap Agent and Runner classes
• Execute agent runs as Exosphere states
• Basic retry support
• Execution tracking in dashboard

Out of Scope (Future)

• Multi-agent handoffs as graph edges
• Streaming responses through Exosphere
• Custom tool execution as separate nodes
• Guardrails integration

---

API Design (Draft)

Simple Usage

from exospherehost.openai import agents

# Define agent (same as OpenAI SDK)
assistant = agents.Agent(
 name="assistant",
 instructions="You help users with questions",
 model="gpt-4o"
)

# Run with Exosphere reliability
result = await agents.run(
 assistant, 
 "What is the capital of France?",
 retry_policy={"max_retries": 3, "strategy": "EXPONENTIAL"}
)

print(result.output)

As Part of a Graph

from exospherehost import BaseNode
from exospherehost.openai import agents

class ResearchAgent(BaseNode):
 class Inputs(BaseModel):
 query: str
 
 class Outputs(BaseModel):
 findings: str
 
 async def execute(self, inputs):
 agent = agents.Agent(
 name="researcher",
 instructions="Find information on the given topic",
 tools=[web_search]
 )
 
 result = await agents.run(agent, inputs.query)
 return self.Outputs(findings=result.output)

---

Implementation Sketch

Module Structure

python-sdk/
 exospherehost/
 openai/
 __init__.py # exports agents
 agents.py # Agent, run() wrapper
 _runner.py # Internal execution logic

Core Wrapper

# exospherehost/openai/agents.py

from openai_agents import Agent as OpenAIAgent, Runner
from exospherehost import StateManager

# Re-export Agent class unchanged
Agent = OpenAIAgent

async def run(agent: Agent, message: str, retry_policy: dict = None):
 """
 Execute an OpenAI agent with Exosphere reliability.
 
 - Tracks execution as a state
 - Applies retry policy on failure
 - Records output for observability
 """
 # For prototype: direct execution with retry wrapper
 # Future: create state in State Manager, execute via Runtime
 
 max_retries = retry_policy.get("max_retries", 0) if retry_policy else 0
 
 for attempt in range(max_retries + 1):
 try:
 result = await Runner.run(agent, message)
 return result
 except Exception as e:
 if attempt == max_retries:
 raise
 # Apply backoff strategy
 await asyncio.sleep(2 ** attempt)

---

Open Questions

1. How deep should integration go?

   • Shallow: Just wrap run() with retries
   • Deep: Each tool call is a separate Exosphere state

2. How to handle streaming?

   • OpenAI SDK supports streaming responses
   • Exosphere doesn't have streaming yet (see exploration: Study impact and effort for streaming to workers #638)

3. Multi-agent handoffs?

   • Model as graph edges between AgentNodes?
   • Or let OpenAI SDK handle internally?

4. Dependency management?

   • Make openai-agents an optional dependency
   • pip install exospherehost[openai]

---

Effort Estimate

Task	Effort
Module structure + exports	0.5 days
Basic run() wrapper with retries	1 day
State tracking integration	1-2 days
Dashboard visibility	1 day
Documentation + examples	1 day
Testing	1 day

Total: 5-7 days for prototype

---

Success Criteria

• Developer can from exospherehost.openai import agents
• Agent execution has automatic retries
• Executions visible in Exosphere dashboard
• Works alongside existing graph-based workflows
• No changes required to existing OpenAI agent code

---

References

• OpenAI Agents SDK Documentation
• OpenAI Agents SDK GitHub
• Current SDK structure: python-sdk/exospherehost/__init__.py