Skip to main content

​
External Agents

PraisonAI provides seamless integration with external AI coding CLI tools, allowing you to use Claude Code, Gemini CLI, Codex CLI, and Cursor CLI as agent tools.

​
Supported Integrations

IntegrationCLI CommandFeatures
Claude CodeclaudeSDK support, session continuation, tool restrictions
Gemini CLIgeminiModel selection, multi-directory context, usage stats
Codex CLIcodexFull auto mode, sandbox modes, structured output
Cursor CLIcursor-agentForce mode, session resume, streaming

​
Installation

The integrations are included with PraisonAI: 
pip install praisonai
You’ll also need to install the respective CLI tools: 
# Claude Code
curl -fsSL https://claude.ai/install.sh | bash

# Gemini CLI
npm install -g @anthropic-ai/gemini-cli

# Codex CLI
npm install -g @openai/codex

# Cursor CLI
# Download from cursor.com

​
Quick Start

​
Python API

from praisonai.integrations import (
    ClaudeCodeIntegration,
    GeminiCLIIntegration,
    CodexCLIIntegration,
    CursorCLIIntegration,
    get_available_integrations
)

# Check which integrations are available
availability = get_available_integrations()
print(availability)
# {'claude': True, 'gemini': True, 'codex': False, 'cursor': True}

# Create an integration
claude = ClaudeCodeIntegration(workspace="/path/to/project")

# Execute a coding task
result = await claude.execute("Refactor the auth module")
print(result)

​
CLI Usage

# Use external agents from the command line
praisonai "Refactor the code" --external-agent claude
praisonai "Analyze codebase" --external-agent gemini
praisonai "Fix bugs" --external-agent codex
praisonai "Add tests" --external-agent cursor

​
As Agent Tools

from praisonai import Agent
from praisonai.integrations import ClaudeCodeIntegration

# Create integration
claude = ClaudeCodeIntegration(workspace="/path/to/project")

# Get tool
tool = claude.as_tool()

# Use with agent
agent = Agent(
    name="Code Assistant",
    role="Software Developer",
    goal="Help with coding tasks",
    tools=[tool]
)

result = agent.start("Refactor the authentication module")

​
CLI Usage: Manager Delegation vs Direct Proxy

PraisonAI now offers two modes for external CLI integration, balancing power and simplicity.

​
Manager Delegation (Default)

When using --external-agent, a manager Agent wraps the external CLI as a subagent tool, providing reasoning and planning capabilities. 
from praisonaiagents import Agent
from praisonai.integrations import ClaudeCodeIntegration

claude = ClaudeCodeIntegration(workspace=".")
manager = Agent(
    name="Manager",
    instructions="Delegate coding tasks to claude_tool.",
    tools=[claude.as_tool()],
    llm="gpt-4o-mini",
)
manager.start("Refactor the auth module")
When to use manager delegation:
  • Multi-step tasks requiring planning
  • Need reasoning across multiple tools
  • Want aggregated responses
  • Complex workflows with decision-making
Manager LLM: Defaults to gpt-4o-mini, configurable via --llm or MODEL_NAME environment variable.

​
Direct Proxy (Escape Hatch)

Use --external-agent-direct for pass-through behavior — fastest execution with no manager overhead. 
# Manager delegation (new default)
praisonai "Say hi in 5 words" --external-agent claude

# Direct proxy (escape hatch)  
praisonai "Say hi in 5 words" --external-agent claude --external-agent-direct
When to use direct proxy:
  • Single-shot calls
  • Scripting scenarios
  • Fastest execution needed
  • No manager LLM overhead wanted

​
Environment Variables

Set the appropriate API keys for each integration: 
# Claude Code
export ANTHROPIC_API_KEY=your-key
# or
export CLAUDE_API_KEY=your-key

# Gemini CLI
export GEMINI_API_KEY=your-key
# or
export GOOGLE_API_KEY=your-key

# Cursor CLI
export CURSOR_API_KEY=your-key

# OpenAI (for Codex)
export OPENAI_API_KEY=your-key

​
ExternalAgentsHandler

The ExternalAgentsHandler provides a unified interface for managing external integrations: 
from praisonai.cli.features import ExternalAgentsHandler

handler = ExternalAgentsHandler()

# List available integrations
integrations = handler.list_integrations()
print(integrations)  # ['claude', 'gemini', 'codex', 'cursor']

# Check availability
availability = handler.check_availability()
print(availability)
# {'claude': True, 'gemini': True, 'codex': False, 'cursor': True}

# Get a specific integration
claude = handler.get_integration("claude", workspace="/project")

​
Performance

All integrations are designed with zero performance impact:
MetricResult
Import time< 1ms
Availability check (first)~1ms
Availability check (cached)~0ms
Memory overheadMinimal (lazy loading)

​
Lazy Loading

Integrations are only imported when used: 
# This does NOT import any integration classes
from praisonai.integrations import get_available_integrations

# This imports only ClaudeCodeIntegration
from praisonai.integrations import ClaudeCodeIntegration

​
Availability Caching

CLI availability checks are cached at the class level: 
from praisonai.integrations import ClaudeCodeIntegration

claude1 = ClaudeCodeIntegration()
claude2 = ClaudeCodeIntegration()

# Both use the same cached availability check
print(claude1.is_available)  # Checks filesystem
print(claude2.is_available)  # Uses cached result

​
Streaming

All integrations support streaming output: 
from praisonai.integrations import ClaudeCodeIntegration

claude = ClaudeCodeIntegration()

async for event in claude.stream("Add error handling to main.py"):
    print(event)
    # {'type': 'assistant', 'content': '...'}
    # {'type': 'tool_use', 'name': 'Write', ...}
    # {'type': 'result', 'content': '...'}

​
Error Handling

from praisonai.integrations import ClaudeCodeIntegration

claude = ClaudeCodeIntegration(timeout=60)

try:
    result = await claude.execute("Complex refactoring task")
except TimeoutError:
    print("Task timed out")
except Exception as e:
    print(f"Error: {e}")

​
Using from PraisonAI UI

Instead of writing Python code, you can enable external agents directly from any PraisonAI UI by flipping toggles in the interface. See External Agents in UI for complete documentation on UI-based external agent management.

​
Next Steps

Claude Code

Detailed Claude Code integration guide

Gemini CLI

Detailed Gemini CLI integration guide

Codex CLI

Detailed Codex CLI integration guide

Cursor CLI

Detailed Cursor CLI integration guide