docs: update --external-agent docs for manager delegation default (PR #1436)

[MervinPraison]

Context

PraisonAI PR #1436 (merged 2026-04-17, fixes #1417) changed the behavior of the --external-agent CLI flag.

This is a content UPDATE task across several existing pages — no new page is required.

---

What Changed in the SDK

Before (old behavior)

praisonai "prompt" --external-agent claude was a pass-through proxy — it bypassed the PraisonAI manager Agent and executed the external CLI directly.

After (new default)

--external-agent X now creates a manager Agent that uses X as a subagent tool. The manager:

1. Receives the user prompt
2. Reasons/plans
3. Calls the external CLI tool when needed (via integration.as_tool())
4. Aggregates the result into a final response

New escape-hatch flag: --external-agent-direct

Preserves the previous proxy behavior as an opt-in.

Implementation details (verified from SDK source)

• File: src/praisonai/praisonai/cli/main.py
• Flag registration (line ~1067):

  parser.add_argument("--external-agent-direct", action="store_true",
                      help="Use external agent as direct proxy (skip manager Agent delegation)")

• Manager construction (line ~4401):

  from praisonaiagents import Agent
  manager = Agent(
      name="Manager",
      instructions=(
          f"You are a manager that delegates tasks to the {external_agent_name} subagent "
          f"via the {integration.cli_command}_tool. Call the tool for coding/analysis tasks."
      ),
      tools=[integration.as_tool()],
      llm=agent_config.get('llm') or os.environ.get("MODEL_NAME", "gpt-4o-mini"),
  )
  result = manager.start(prompt)

• --external-agent still accepts: claude | gemini | codex | cursor
• Default manager LLM: gpt-4o-mini (override via --llm / MODEL_NAME env var)
• Unavailable CLI now surfaces an install hint and returns None

---

Files to Update

All files below already exist — edit in place. Do not create new pages unless explicitly noted. Do not touch docs/concepts/ (human-approved only).

1. docs/cli/cli-reference.mdx (REQUIRED)

• In the Global Flags table (around line 259), add a new row directly under --external-agent:

  | `--external-agent-direct` | flag | Use external agent as direct proxy (skip manager Agent delegation) |
  

• Update the --external-agent row description to reflect the new default:

  | `--external-agent` | str | External CLI tool (claude/gemini/codex/cursor) — uses manager-Agent delegation by default |
  

• Update the "Common Flag Combinations" example (around line 382) so the comment reads "delegated via manager" and add an adjacent example with --external-agent-direct.

2. docs/code/external-agents.mdx (REQUIRED — largest rewrite)

Current page (around line 72–78) shows CLI usage as:

praisonai "Refactor the code" --external-agent claude

This now means manager delegation, which must be documented.

Add a new top-level section "CLI Usage: Manager Delegation vs Direct Proxy" (after the existing "CLI Usage" section) that covers:

• How --external-agent works now (manager Agent + subagent tool)
  • Include a Mermaid sequenceDiagram using the standard colour scheme (#8B0000, #189AB4, #10B981, #F59E0B, #6366F1; white text) showing: User → Manager Agent → External CLI Tool → Manager Agent → User
• When to use the new default (reasoning, multi-step planning, aggregation across tools)
• When to use --external-agent-direct (pass-through, fastest, no LLM manager overhead)
• Side-by-side example:

  # 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

• Manager LLM note: default is gpt-4o-mini, configurable via --llm or MODEL_NAME env var.

Also add an agent-centric example near the top (per AGENTS.md principle #9 — "Documentation need to be agent centric"):

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")

This is the exact pattern the CLI now uses under the hood — showing it makes the abstraction concrete.

3. docs/features/external-cli-integrations.mdx (REQUIRED)

Add a new section "CLI: Manager Delegation (Default)" after "Quick Start" explaining the two modes. Use:

• A Mermaid decision diagram (graph TB) to help users choose between default manager mode and --external-agent-direct

• A small comparison table:

  Mode	Flag	Behaviour	Best for
  Manager delegation (default)	--external-agent X	Manager Agent wraps the CLI as a tool, reasons, then calls it	Multi-step tasks, planning, aggregation
  Direct proxy	--external-agent X --external-agent-direct	Pass-through — CLI runs the prompt verbatim	Fast single-shot calls, scripting, when you don't want a manager LLM

4. Per-CLI pages (REQUIRED — small edit in each)

Update the "Basic Usage with PraisonAI" section in each of:

• docs/cli/claude-cli.mdx (around lines 37–45)
• docs/cli/gemini-cli.mdx
• docs/cli/codex-cli.mdx
• docs/cli/cursor-cli.mdx

For each, add a <Note> callout explaining that --external-agent <name> invokes the CLI via a manager Agent by default, and show the --external-agent-direct escape hatch:

# Manager delegation (default — manager reasons + calls claude as subagent tool)
praisonai "Fix the bug in auth.py" --external-agent claude

# Direct proxy (escape hatch — no manager, passes prompt straight to claude)
praisonai "Fix the bug in auth.py" --external-agent claude --external-agent-direct

---

Style & Compliance Checklist (from AGENTS.md)

The implementing agent must follow these — do not skip:

• Read the SDK source (src/praisonai/praisonai/cli/main.py around lines 1067 and 4367–4425) before writing
• Keep content user-focused, not SDK-reference-focused (AGENTS.md §1.1 rule 6)
• Agent-centric opening for the big rewrite on docs/code/external-agents.mdx (AGENTS.md §1.1 rule 9)
• Include a user-interaction flow — show what the user types and what they see back (AGENTS.md §1.1 rule 10)
• Where multiple options exist on one page, include a Mermaid decision diagram so readers know which to pick (AGENTS.md §6.1)
• Use the standard Mermaid colour scheme (#8B0000, #189AB4, #10B981, #F59E0B, #6366F1; white text, #7C90A0 strokes) — AGENTS.md §3.1
• Use Mintlify components: <Steps>, <AccordionGroup>, <CardGroup>, <Tabs>, <Note> as appropriate
• Use the simple import style: from praisonaiagents import Agent (AGENTS.md §6.1)
• Do NOT place anything in docs/concepts/ (AGENTS.md §1.8 — human-approved only)
• Do NOT touch docs/js/ or docs/rust/ for this change (auto-generated — AGENTS.md §1.7)
• Short, direct prose — avoid the forbidden phrases listed in AGENTS.md §6.3
• Verify docs.json remains valid JSON if any nav changes are made (none expected for this issue)

---

Acceptance Criteria

• docs/cli/cli-reference.mdx lists --external-agent-direct in the global flags table
• docs/code/external-agents.mdx has a new "Manager Delegation vs Direct Proxy" section with a Mermaid sequence diagram and agent-centric example
• docs/features/external-cli-integrations.mdx documents the two CLI modes with a decision diagram and comparison table
• All four per-CLI pages (claude-cli.mdx, gemini-cli.mdx, codex-cli.mdx, cursor-cli.mdx) explain both modes in their "Basic Usage" section
• No changes under docs/concepts/, docs/js/, or docs/rust/
• All code examples are copy-paste runnable and match the SDK exactly

---

References

• PR: fix: change --external-agent to use manager Agent delegation by default PraisonAI#1436
• Original bug report: Bug: --external-agent proxies the CLI instead of delegating via the PraisonAI manager Agent PraisonAI#1417
• SDK file: src/praisonai/praisonai/cli/main.py (flag at ~L1067, manager logic at ~L4367–4425)

[MervinPraison]

Claude finished @MervinPraison's task —— View job • claude/issue-171-20260417-0624 • [Create PR ➔](https://github.com/MervinPraison/PraisonAIDocs/compare/main...claude/issue-171-20260417-0624?quick_pull=1&title=Issue%20%23171%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%23171%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

Updating --external-agent Documentation ✅

Successfully updated documentation for the new --external-agent behavior and --external-agent-direct flag.

Todo List:

• Set up git identity and read AGENTS.md guidelines
• Read SDK source code to understand implementation details
• Update docs/cli/cli-reference.mdx - add new flag to global flags table
• Update docs/code/external-agents.mdx - add manager delegation vs direct proxy section
• Update docs/features/external-cli-integrations.mdx - add CLI modes section
• Update per-CLI pages: claude-cli.mdx, gemini-cli.mdx, codex-cli.mdx, cursor-cli.mdx
• Verify all changes follow AGENTS.md compliance checklist
• Commit changes and create PR

Summary

Completed all documentation updates to reflect PraisonAI PR #1436 changes:

• New behavior: --external-agent now uses manager Agent delegation by default
• Escape hatch: --external-agent-direct preserves old direct proxy behavior
• Documentation updated: 7 files across CLI reference, feature guides, and per-CLI pages
• Compliance verified: Follows AGENTS.md guidelines for structure, colors, and examples

Pull Request Created

🔗 View PR #172

All acceptance criteria from the issue have been met:

• ✅ CLI reference includes new flag
• ✅ Manager delegation vs direct proxy fully documented
• ✅ Mermaid diagrams with standard color scheme
• ✅ Agent-centric examples included
• ✅ All code examples are copy-paste runnable

Job run | Branch: claude/issue-171-20260417-0624