External CLI Integrations

Drive external AI CLIs like Claude Code from a PraisonAI agent

Drive external AI CLIs from a PraisonAI agent — Claude Code is the flagship integration.

from praisonaiagents import Agent
from praisonai.integrations import ClaudeCodeIntegration

agent = Agent(
    name="coder",
    tools=[ClaudeCodeIntegration().as_tool()],
)
agent.start("Summarise the README in this repo")

The user asks in chat; the agent invokes Claude Code or another external CLI through the integration tool.

Quick Start

1. Attach Claude Code as an agent tool

   from praisonaiagents import Agent
   from praisonai.integrations import ClaudeCodeIntegration
   
   agent = Agent(
       name="coder",
       tools=[ClaudeCodeIntegration().as_tool()],
   )
   agent.start("Summarise the README in this repo")

2. One-shot call via the integration API

   import asyncio
   from praisonai.integrations import ClaudeCodeIntegration
   
   integration = ClaudeCodeIntegration()
   result = asyncio.run(integration.execute("Summarise the README in this repo"))
   print(result)

3. Continue a previous Claude Code session

   # First turn
   await integration.execute("List the open bugs")
   
   # Continue the same session — you MUST pass continue_session=True explicitly
   await integration.execute("Now suggest fixes for the first one", continue_session=True)

4. Stream events live

   async for event in integration.stream("Refactor utils.py"):
       print(event)   # parsed JSON events from the CLI

   The timeout argument is enforced end-to-end: stream_async(timeout=...) applies a monotonic deadline to every stdout read and the final drain, so a stalled claude/gemini/codex/cursor subprocess raises TimeoutError: Stream timed out after {timeout}s: {cmd} instead of hanging forever.

5. Per-call output format

   await integration.execute("prompt", output_format="json")
   await integration.execute("prompt", output_format="text")

6. Register as a native async tool

   from praisonaiagents import Agent
   from praisonai.integrations import ClaudeCodeIntegration
   
   agent = Agent(
       name="coder",
       tools=[ClaudeCodeIntegration().as_async_tool()],  # awaited on the running loop
   )
   
   # Use the async entrypoint on the agent to keep everything on one loop:
   await agent.astart("Summarise the README in this repo")

   as_async_tool() returns a coroutine tool named <cli>_atool (for example claude_atool). It is functionally equivalent to as_tool(), but with no thread hop — measurable when the agent invokes the CLI many times in one turn.

How It Works

The integration builds CLI arguments dynamically per call, with no instance state mutated during execution.

Stateless Session Management

Before (stateful):

# ❌ Old pattern — relied on implicit session state
integration = ClaudeCodeIntegration()
await integration.execute("step 1")  # marks _session_active = True
await integration.execute("step 2")  # implicitly continued previous session
integration.reset_session()           # cleared state

After (stateless):

# ✅ New pattern — explicit, stateless, safe for concurrent use
integration = ClaudeCodeIntegration()
await integration.execute("step 1")
await integration.execute("step 2", continue_session=True)   # explicit
# reset_session() is no longer needed; it is a deprecated no-op

CLI: Manager Delegation (Default)

PraisonAI CLI offers two execution modes for external agents, providing flexibility between automated reasoning and direct execution.

Usage Examples:

# Manager delegation - manager reasons, then calls claude as tool
praisonai "Fix the bug in auth.py" --external-agent claude

# Direct proxy - no manager overhead, straight to claude  
praisonai "Fix the bug in auth.py" --external-agent claude --external-agent-direct

Configuration Options

Registry

The ExternalAgentRegistry manages all available CLI integrations with a thread-safe registry pattern with lazy module-level default. You can construct your own ExternalAgentRegistry() for test isolation or multi-tenant runs:

from praisonai.integrations.registry import get_default_registry

# Default registry (recommended for app code)
registry = get_default_registry()

# List available integrations
available = await registry.get_available()
print(available)  # {'claude': True, 'gemini': False, ...}

# Option 1 — soft lookup: returns None if the integration is missing/unavailable
claude = registry.try_create("claude", workspace="/path/to/project")
if claude is None:
    print("Integration 'claude' not found or unavailable")

# Option 2 — strict: raises ValueError with diagnostics if not registered
claude = registry.create("claude", workspace="/path/to/project")

The existing helpers get_registry(), register_integration(), create_integration(), and get_available_integrations() are still exported and still work — they now delegate to get_default_registry(). Backward-compat code does not need to change.

Invalidating the availability cache

BaseCLIIntegration caches the result of shutil.which(cli_command) for each CLI. If a CLI is installed/uninstalled mid-run (e.g. in tests, or after a setup step), invalidate the cache:

from praisonai.integrations.base import BaseCLIIntegration

# Clear cache for one command
BaseCLIIntegration.invalidate_availability("claude")

# Clear the entire cache
BaseCLIIntegration.invalidate_availability()

The cache is thread-safe; invalidation is also thread-safe.

Logging for embedders

The registry logs through the named logger praisonai.integrations.registry — it never configures the root logger, so importing or calling the registry will not install a handler on an embedding application’s root logger.

Two warnings route through this logger:

Silence or redirect them:

import logging

logging.getLogger("praisonai.integrations.registry").setLevel(logging.ERROR)

Registering the integration as a tool

Both methods wrap the same underlying integration.execute(query) coroutine — pick the one that matches how your agent is invoked.

<cli> is the integration’s cli_command: claude_tool/claude_atool, gemini_tool/gemini_atool, codex_tool/codex_atool, and cursor-agent_tool/cursor-agent_atool.

Register a custom external agent

Register your own external agent once and it becomes reachable from every surface — --external-agent, the praisonai_code CLI handler, and the UI toggles — with no PraisonAI code changes.

1. Ship as a pip plugin (recommended)

   Publish your integration class to the praisonai.external_agents entry-point group:

   # your-plugin/pyproject.toml
   [project.entry-points."praisonai.external_agents"]
   aider = "acme_aider:AiderIntegration"

   After pip install your-plugin, aider appears in praisonai --external-agent choices, in the praisonai_code CLI handler, and as a UI toggle — no PraisonAI code changes.

2. Or register at runtime

   from praisonai.integrations.registry import get_default_registry
   from praisonai.integrations.base import BaseCLIIntegration
   
   class AiderIntegration(BaseCLIIntegration):
       display_label = "Aider (pair programming)"
       install_hint = "pip install aider-chat"
   
       @property
       def cli_command(self) -> str:
           return "aider"
   
       async def execute(self, prompt: str, **options) -> str: ...
       async def stream(self, prompt: str, **options): ...
   
   get_default_registry().register("aider", AiderIntegration)

   register() raises ValueError if the class does not inherit BaseCLIIntegration.

Presentation metadata

Two optional class attributes drive help text, UI labels, and install hints on every surface:

Built-ins declare them too:

Single source of truth

Two registry helpers back every surface that lists external agents:

from praisonai.integrations.registry import (
    list_external_agents,
    external_agent_catalog,
)

# Names of every registered external agent (built-ins + plugins)
list_external_agents()
# ['claude', 'gemini', 'codex', 'cursor', 'aider']

# Presentation metadata per agent: {"cls", "label", "cli", "install"}
external_agent_catalog()["aider"]
# {'cls': AiderIntegration, 'label': 'Aider (pair programming)',
#  'cli': 'aider', 'install': 'pip install aider-chat'}

Built-ins keep declaration order (claude, gemini, codex, cursor); plugins are appended in sorted order behind them. A faulty optional plugin is logged and skipped — it never blanks the catalog. Name collisions between a third-party plugin and a built-in are resolved in favour of the built-in — a plugin can extend the catalog but never replace claude, gemini, codex, or cursor.

A listed name is always a usable name. list_external_agents() is derived from external_agent_catalog(), so a plugin that fails to import disappears from both surfaces at once. A broken plugin is never advertised as a --external-agent choice and then rejected by the handler — if the name shows up in --help, in ExternalAgentsHandler().list_integrations(), or as a UI toggle, it loads.

Which entry-point group?

Two entry-point groups exist and are easy to confuse — pick by outcome:

Use praisonai.external_agents for a selectable --external-agent short name and a UI toggle. Use praisonai.integrations only to make a class importable from praisonai.integrations.

Prerequisites

The claude CLI must be available on PATH or the Claude Code SDK must be installed if use_sdk=True. The integration performs a cached, thread-safe shutil.which(...) check via is_available().

# Install Claude Code CLI (option 1)
# Follow Claude Code installation instructions

# Or install SDK (option 2)  
pip install claude-agent-sdk

Decision Flow

Best Practices

# ✅ Good - explicit session control
await integration.execute("step 1")
await integration.execute("step 2", continue_session=True)

# ❌ Bad - relying on removed implicit state
await integration.execute("step 1")
await integration.execute("step 2")  # No longer continues session

# ✅ Good - per-call parameter
await integration.execute("prompt", output_format="json")
await integration.execute("prompt", output_format="text")

# ✅ Good - set once in constructor
integration = ClaudeCodeIntegration(output_format="json")

# ❌ Bad - mutating instance attribute
integration.output_format = "json"  # Don't do this

# ❌ Bad - calling deprecated no-op
integration.reset_session()

# ✅ Good - just omit the call
# Session state is automatically stateless

# ✅ Good - concurrent safe
integration = ClaudeCodeIntegration()

async def task1():
    return await integration.execute("task 1")

async def task2(): 
    return await integration.execute("task 2")

# Both tasks can run concurrently safely
results = await asyncio.gather(task1(), task2())

Troubleshooting

import logging
logging.basicConfig(level=logging.WARNING)

from praisonai.integrations.registry import list_external_agents
list_external_agents()

your installed 'praisonai' wrapper is too old for --external-agent (missing external_agent_catalog); upgrade with: pip install -U praisonai

pip install -U praisonai

Using from PraisonAI UI

Related