External Agents

Integrate external AI coding CLI tools as PraisonAI agent tools

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

Integration	CLI Command	Features
Claude Code	claude	SDK support, session continuation, tool restrictions
Gemini CLI	gemini	Model selection, multi-directory context, usage stats
Codex CLI	codex	Full auto mode, sandbox modes, structured output
Cursor CLI	cursor-agent	Force 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:

Metric	Result
Import time	< 1ms
Availability check (first)	~1ms
Availability check (cached)	~0ms
Memory overhead	Minimal (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