> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonai
```

You'll also need to install the respective CLI tools:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Manager as Manager Agent
    participant CLI as External CLI Tool
    participant User2 as User (Direct)
    participant CLI2 as External CLI Tool (Direct)
    
    Note over User,CLI: Manager Delegation (Default)
    User->>Manager: "Refactor auth.py"
    Manager->>CLI: Call claude_tool
    CLI-->>Manager: Result
    Manager-->>User: Aggregated response
    
    Note over User2,CLI2: Direct Proxy (--external-agent-direct)
    User2->>CLI2: "Refactor auth.py"
    CLI2-->>User2: Direct result
    
    classDef user fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef manager fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef cli fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff
    
    class User,User2 user
    class Manager manager
    class CLI,CLI2 cli
```

### Manager Delegation (Default)

When using `--external-agent`, a manager Agent wraps the external CLI as a subagent tool, providing reasoning and planning capabilities.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

<Tip>
  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](/docs/features/external-agents-ui) for complete documentation on UI-based external agent management.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Claude Code" icon="message-bot" href="/docs/code/claude-code">
    Detailed Claude Code integration guide
  </Card>

  <Card title="Gemini CLI" icon="google" href="/docs/code/gemini-cli">
    Detailed Gemini CLI integration guide
  </Card>

  <Card title="Codex CLI" icon="openai" href="/docs/code/codex-cli">
    Detailed Codex CLI integration guide
  </Card>

  <Card title="Cursor CLI" icon="cursor" href="/docs/code/cursor-cli">
    Detailed Cursor CLI integration guide
  </Card>
</CardGroup>