OpenAI Agents SDK Integration¶

Build production-ready ReAct agents using the OpenAI Agents SDK with Nexus filesystem - same capabilities as LangGraph but with 70% less code and automatic ReAct loop handling.

🎯 What is OpenAI Agents SDK + Nexus?¶

The OpenAI Agents SDK is a production-ready framework for building agentic AI applications. When combined with Nexus, you get intelligent agents that can:

• Search and analyze files using grep, glob, and semantic search
• Read and write files with persistent storage across runs
• Remember information using Nexus Memory API
• Reason and act automatically with built-in ReAct loop
• Collaborate via shared filesystem and multi-tenancy

Why This Matters¶

Traditional file agents require: - Manual ReAct loop implementation (~100 lines) - State management boilerplate - Session persistence logic - Memory storage setup

OpenAI Agents SDK + Nexus handles all of this automatically:

# Just define tools and run!
@function_tool
async def grep_files(pattern: str, path: str = "/") -> str:
    """Search file content."""
    return nx.grep(pattern, path)

agent = Agent(name="FileAgent", tools=[grep_files])
result = Runner.run_sync(agent, "Find all async/await patterns")

📊 Demo: Code Analysis Agent¶

The demo shows an agent that analyzes Python codebases for async patterns. It automatically searches files, reads relevant code, analyzes patterns, and generates a summary report.

What the Demo Shows¶

An AI agent that:

1. Searches for files containing async/await patterns
2. Reads relevant Python files to understand usage
3. Analyzes patterns and identifies common practices
4. Writes a comprehensive markdown report
5. All automatically through ReAct loop reasoning

Quick Start¶

Option A: All-in-one script (Recommended)

cd examples/openai_agents

# Set OpenAI API key
export OPENAI_API_KEY="sk-..."

# Run complete demo (starts server, creates files, runs agent)
./openai_agent_react_demo.sh

Option B: Manual execution

# Install dependencies
cd examples/openai_agents
pip install -r requirements.txt

# Set API keys
export OPENAI_API_KEY="sk-..."

# Run demos
python openai_agent_react_demo.py  # File analysis
python memory_agent_demo.py        # Persistent memory

🔬 How It Works¶

The Automatic ReAct Loop¶

Unlike LangGraph where you manually build the ReAct loop, OpenAI Agents SDK handles it automatically:

graph TB
    Start([🎯 Start<br/>User Task]) --> Agent[🤖 Agent Reasoning<br/>GPT-4 thinks about task]

    Agent --> Decide{Need<br/>Tools?}

    Decide -->|Yes| Select[🔧 Select Tool<br/>grep_files, read_file, etc.]
    Decide -->|No| Done([✅ Complete<br/>Return response])

    Select --> Execute[⚙️ Execute Tool<br/>Search/read files via Nexus]

    Execute --> Observe[👁️ Observe Results<br/>Tool returns data]

    Observe --> Agent

    style Start fill:#e1f5ff,stroke:#0288d1,stroke-width:3px
    style Agent fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
    style Execute fill:#fff9c4,stroke:#f57c00,stroke-width:2px
    style Observe fill:#fce4ec,stroke:#c2185b,stroke-width:2px
    style Done fill:#a5d6a7,stroke:#2e7d32,stroke-width:3px

What happens automatically:

1. Agent Reasoning - LLM thinks about the task
2. Tool Selection - Decides which tool to call (grep_files, read_file, etc.)
3. Tool Execution - Nexus tools run and return results
4. Observation - Agent sees results and reasons about next step
5. Loop - Repeats until task is complete

All without writing state management code!

Core Components¶

1. Nexus Tools (@function_tool)¶

Transform Nexus filesystem operations into agent tools:

from agents import function_tool

@function_tool
async def grep_files(pattern: str, path: str = "/") -> str:
    """Search file content using grep patterns."""
    results = nx.grep(pattern, path)
    # Format and return results
    return formatted_results

@function_tool
async def read_file(path: str, preview: bool = False) -> str:
    """Read file content."""
    content = nx.read(path).decode('utf-8')
    return content if not preview else content[:1000]

@function_tool
async def write_file(path: str, content: str) -> str:
    """Write content to file."""
    nx.write(path, content.encode('utf-8'))
    return f"Wrote to {path}"

2. Agent Creation¶

Create an agent with tools and instructions:

from agents import Agent

agent = Agent(
    name="FileAnalyzer",
    instructions="""You are a code analysis assistant.

    Use grep_files to search for patterns.
    Use read_file to examine code.
    Use write_file to save reports.""",
    tools=[grep_files, read_file, write_file],
    model="gpt-4o"
)

3. Execution¶

Run the agent with automatic ReAct loop:

from agents import Runner

result = Runner.run_sync(
    agent,
    "Find all async/await patterns and create a summary"
)
print(result.final_output)

💡 Use Cases¶

1. Code Analysis & Documentation¶

Automatically analyze codebases and generate documentation:

agent = Agent(
    name="CodeAnalyzer",
    instructions="Analyze code structure and generate documentation",
    tools=[grep_files, glob_files, read_file, write_file]
)

Runner.run_sync(agent, """
Find all API endpoint definitions in /src and create
comprehensive API documentation in /docs/api.md
""")

2. TODO/FIXME Tracker¶

Scan codebase for TODOs and generate task lists:

Runner.run_sync(agent, """
Find all TODO and FIXME comments in the codebase.
Categorize by priority and create a task list in /reports/todos.md
""")

3. Research Agent with Memory¶

Agent that remembers findings across sessions:

@function_tool
async def store_memory(content: str, memory_type: str = "fact") -> str:
    """Store information in persistent memory."""
    nx.memory.store(content, scope="agent", memory_type=memory_type)
    return f"Stored {memory_type}"

@function_tool
async def recall_memory(query: str) -> str:
    """Query stored memories."""
    results = nx.memory.query(query, scope="agent")
    return format_memories(results)

# Agent remembers across sessions!
agent = Agent(
    name="ResearchAgent",
    instructions="Research topics and remember key findings",
    tools=[grep_files, read_file, store_memory, recall_memory]
)

4. Migration Assistant¶

Find and update deprecated patterns:

Runner.run_sync(agent, """
Find all uses of deprecated function 'old_api()'.
Read the files, understand context, and create a migration
plan in /docs/migration-plan.md
""")

📊 Comparison with Other Frameworks¶

See COMPARISON.md for detailed side-by-side comparison with code examples and migration guides.

⚙️ Configuration¶

Remote Nexus Server¶

export NEXUS_SERVER_URL="http://your-server:2026"
export NEXUS_API_KEY="your-api-key"

Multi-Tenancy¶

export NEXUS_TENANT_ID="my-team"
export NEXUS_AGENT_ID="file-analyzer"

Local Testing¶

# Terminal 1: Start Nexus server
nexus serve --port 2026

# Terminal 2: Run agent
export NEXUS_SERVER_URL="http://localhost:2026"
python openai_agent_react_demo.py

🔧 Available Tools¶

File Operations¶

Memory Operations¶

🔍 Troubleshooting¶

"OPENAI_API_KEY not found"¶

export OPENAI_API_KEY="sk-..."

"Error connecting to Nexus"¶

1. Check server: curl http://your-server:2026/health
2. Try local: nexus serve
3. Set URL: export NEXUS_SERVER_URL="http://localhost:2026"

"Module not found"¶

pip install -r requirements.txt

📦 Example Files¶

All examples are in examples/openai_agents/:

• openai_agent_react_demo.py - File operations demo (port of LangGraph demo)
• memory_agent_demo.py - Persistent memory demo
• nexus_tools.py - Reusable tool definitions
• COMPARISON.md - Detailed framework comparison
• README.md - Complete setup guide

✨ Key Benefits¶

✅ Automatic ReAct - No manual state management ✅ 70% Less Code - vs. LangGraph implementation ✅ Persistent Memory - Nexus Memory API integration ✅ Agent Handoffs - Native multi-agent collaboration ✅ Production Ready - Guardrails, validation, error handling ✅ Multi-Tenancy - Isolated workspaces per team ✅ Semantic Search - Find files by meaning

🚀 Next Steps¶

• Run the Examples - Try the demos
• Read COMPARISON.md - Compare frameworks
• Explore LangGraph - Alternative approach
• Nexus API Reference - Full API documentation

📚 Resources¶

• OpenAI Agents SDK Documentation
• Nexus GitHub Repository
• Example Source Code