Skip to content

Docs sync: cover recent PraisonAI features (PRs #2267, #2244, #1367, #2243, #2245, #2240, #2269, #2250, #2248, #1889) #895

Closed
#896
Closed
Docs sync: cover recent PraisonAI features (PRs #2267, #2244, #1367, #2243, #2245, #2240, #2269, #2250, #2248, #1889)#895
#896
Labels
bugSomething isn't workingclaudeTrigger Claude Code analysisdocumentationImprovements or additions to documentation

Description

@MervinPraison
MervinPraison
opened on Jun 25, 2026

Overview

PraisonAI has shipped a batch of user-facing changes in the last ~2 weeks (releases v4.6.74 → v4.6.76) that need to be reflected in PraisonAIDocs. I audited the docs tree against the merged PRs and grouped the work into one new page plus a set of targeted updates to existing pages.

All work below MUST follow AGENTS.md in this repo:

  • New pages live in docs/features/ (never docs/concepts/ — human-approved only).
  • Read the SDK source for each feature before writing — do not guess signatures.
  • Hero Mermaid diagram + Quick Start (Steps) + Config table + AccordionGroup best-practices + Related CardGroup on every new page.
  • Standard color palette (#8B0000, #189AB4, #10B981, #F59E0B, #6366F1, white text).
  • Agent-centric examples up top. Use simple imports: from praisonaiagents import Agent.
  • After adding any new page, append it to the "Features" group in docs.json (NOT "Concepts").

A downstream agent will implement these — this issue is the spec.

1. NEW PAGE — /learn skill authoring (PR #2267)

Path: docs/features/agent-learn-skill.mdx

Why: None of the existing skill pages (skill-lifecycle.mdx, skill-manage.mdx, self-improve.mdx) reference the new Agent.learn(request) API, the /learn slash command, or build_learn_prompt. The two concept pages docs/concepts/agent-learn.mdx and docs/concepts/learn-vs-train.mdx exist but are human-only and don't cover the wrapper/CLI surface.

SDK files to read (mandatory):

  • praisonaiagents/skills/learn.py — build_learn_prompt(request) (grounded skill-authoring directive)
  • praisonaiagents/agent/execution_mixin.py — Agent.learn(request) and _ensure_skill_management_tools()
  • praisonai/bots/_commands.py — /learn registration and handle_learn_command(agent, request)

What the page must cover (from the PR body):

Point the agent at source material — a codebase, API docs, PDFs, configs, or the current chat — and have it distil one grounded SKILL.md in a single command. Curated prompt + thin entry points on top of skill_manage + file/PDF readers.

Two minimal examples up top (agent-centric, then bot):

from praisonaiagents import Agent

agent = Agent(name="Skill Author", instructions="You learn and write skills.")
agent.learn("Read ./my-repo and the docs in ./docs/*.pdf and make a 'deploy-flow' skill")
/learn deploy steps from this repo and the runbook PDF

Sections required:

  • Quick Start (<Steps>): (1) agent.learn(request) one-liner, (2) /learn in Telegram/Slack/Discord, (3) backward-compat alias learn / alearn.
  • How It Works sequence diagram: User → Agent → build_learn_prompt → skill_manage writes SKILL.md.
  • What the grounded prompt enforces (verbatim from build_learn_prompt): gather named sources, use only verbatim flags/paths/APIs, keep SKILL.md ~100–200 lines, move long material to supporting files.
  • Authorization note: PR #2269 makes /learn admin-only by default when a CommandAccessPolicy is configured — link to bot-command-access-control.mdx.
  • Related CardGroup: skill-manage.mdx, skill-lifecycle.mdx, bot-commands.mdx, self-improve.mdx.

docs.json: add under "Features" group.

2. UPDATE — docs/features/bot-commands.mdx: list /learn

PR #2267 adds /learn as a first-class gateway slash command. The current page lists /model, /usage, /compress, /queue but not /learn. Add it to the command table with a one-line description and a link to the new agent-learn-skill.mdx page. Note its admin-only default.

3. UPDATE — docs/features/bot-run-control.mdx: programmatic steering API (PR #2244)

SDK files to read:

  • praisonai/bots/_run_control.py — RunDecision.STEERED, SessionRunState.agent, register_agent(user_id, agent), submit() STEER branch
  • praisonai/bots/_session.py — chat_with_run_control auto-registers the live agent
  • praisonaiagents/agent/message_steering.py and execution_mixin.py — core agent.steer(text, priority=30) (uses SteeringPriority.INTERRUPT)

Gap: the page documents the user-visible STEER ack, but not the programmatic surface. Add a section explaining:

  • agent.steer(text, priority=30) injects mid-run guidance into the live agent's steering queue (priority 30 = SteeringPriority.INTERRUPT).
  • The RunDecision enum, especially the new STEERED value (vs. QUEUE, IGNORE, etc.).
  • Fallback path: if no agent is registered OR the agent has steering disabled, submit() silently falls back to QUEUE.
  • register_agent(user_id, agent) / finish_run() / stop() lifecycle.

Include a minimal example:

agent.steer("Stop summarising — return raw JSON instead", priority=30)

4. UPDATE — Sandbox docs (BREAKING CHANGE, PR #1367)

Pages: docs/features/sandbox.mdx, docs/features/sandbox-backends.mdx, and a row in docs/features/fail-loud-defaults.mdx.

SDK file to read:

  • praisonai/sandbox/sandlock.py

Breaking change to document:

SandlockSandbox.__init__ now raises RuntimeError when Landlock ABI < min (currently v6, Linux 6.12+). Previously it silently fell back to SubprocessSandbox.

Required additions:

  • Kernel requirement callout (<Warning>): Landlock ABI ≥ v6, Linux ≥ 6.12, seccomp not stripped (containers).
  • The graceful-degradation pattern:
try:
    sb = SandlockSandbox(cfg)
except (ImportError, RuntimeError):
    sb = SubprocessSandbox(cfg)
  • Other behaviour changes worth a single line each:
    • clean_env=True default isolates host env.
    • stdout/stderr decoded to str (no more bytes).
    • max_cpu from limits.cpu_percent is now actually applied.
    • Timeout detection via exit_code == -1 (sandlock's structural sentinel).
    • Network policy semantics: net_connect=["0-65535"] when enabled, net_allow_hosts=[] when disabled.
    • execute_file() invokes script by path, not -c <slurped source>.
  • Add a row in fail-loud-defaults.mdx summarising the silent-fallback removal.

5. UPDATE — Autogen adapter removal (PR #2248)

Pages: docs/features/tool-registry-autogen-migration.mdx, docs/features/thread-safety.mdx.

Both pages currently describe ToolRegistry.register_autogen_adapter, get_autogen_adapter, list_autogen_adapters, register_builtin_autogen_adapters as "available for backward compatibility" (citing PR #1780). PR #2248 has now removed them. Update language from deprecated → removed. Point migration explicitly to praisonai.persistence.factory and any docs/persistence/ page.

Also: mark storage/ as legacy where referenced and link forward to docs/persistence/.

6. UPDATE — Typed handoffs (PR #1889)

Page: docs/features/typed-handoffs.mdx

The page already covers Pydantic-validated payloads. The keyword input_payload_schema (the receiving-agent parameter) did NOT appear in a code search of the docs. Add at least one example showing it on the receiving side:

class DeployPayload(BaseModel):
    service: str
    version: str

receiver = Agent(name="Deployer", input_payload_schema=DeployPayload, ...)

Mention HandoffValidationError on mismatch.

7. VERIFY — Bot command access control framing (PR #2269)

Page: docs/features/bot-command-access-control.mdx

PR #2269 lifts CommandAccessPolicy from Telegram-only to shared bots-level, applying uniformly to Slack and Discord. Verify the page:

  • Is not framed as Telegram-only anywhere.
  • Lists /learn as admin-only by default (it's in PRIVILEGED_COMMANDS).
  • Mentions both admin_users and user_allowed_commands knobs.

8. Already covered (no action needed) — for reviewer cross-check

The following PRs are already adequately documented; flag if you spot drift while in the area:

PR Existing doc Notes
#2243 Runtime MCP management docs/features/runtime-mcp.mdx All four methods (add_mcp_server, remove_mcp_server, refresh_tools, list_mcp_servers) covered.
#2245 /model /usage /compress /queue docs/features/bot-commands.mdx All four listed.
#2240 Code-mode tool bridging docs/features/code-execution-with-tools.mdx code_tools, code_tools_allow, ToolProxy, approval gate all covered.
#2250 Structured tool retry/backoff docs/features/tool-retry-policy.mdx, docs/features/concurrency.mdx retry_on={"timeout","rate_limit","connection_error"} appears verbatim.

Quality checklist for the doc-author agent

For each new/updated page:

  • SDK file(s) listed above read end-to-end before writing
  • All config options, types, defaults match SDK exactly
  • Quick Start example is the shortest working snippet, uses from praisonaiagents import Agent
  • Hero Mermaid diagram present (standard color palette, white text)
  • <Steps>, <AccordionGroup>, <CardGroup> components used per AGENTS.md template
  • No forbidden phrases ("In this section…", "It's important to note…", "As you can see…")
  • New pages added under "Features" group in docs.json (NOT "Concepts")
  • No edits to anything under docs/concepts/ (human-approved only)

Source-of-truth pointers

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingclaudeTrigger Claude Code analysisdocumentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions