Context

PR MervinPraison/PraisonAI#1526 ("feat: separate managed runtime vs sandboxed tool execution", merged 2026-04-24, fixes #1523) introduces a Phase-1 architectural split between managed runtime (remote agent loop) and sandboxed tool execution (local agent loop, remote tools), along with a set of new configuration classes and CRUD APIs on AnthropicManagedAgent.

None of the new symbols (ManagedRuntimeProtocol, SandboxedAgent, SandboxedAgentConfig, NetworkingConfig, PackagesConfig, NetworkingType, VaultManager, and new agent/environment/session CRUD methods) currently appear anywhere under docs/. The existing concept pages (docs/concepts/managed-agents*.mdx) still describe the old model. This issue tracks the documentation work required to align PraisonAIDocs with the merged SDK changes.

Per AGENTS.md:

• docs/concepts/ is HUMAN APPROVAL ONLY — any rename/update of managed-agents-local.mdx or managed-agents.mdx requires explicit human sign-off. Agents working this issue must not silently edit concept pages.
• New feature pages go under docs/features/.

Summary of the SDK changes (what needs to be documented)

1. New honest naming (backward-compatible aliases)

• LocalManagedAgent → SandboxedAgent
• LocalManagedConfig → SandboxedAgentConfig
• Source: src/praisonai/praisonai/integrations/sandboxed_agent.py, managed_local.py (aliases at the bottom)
• Both names resolve to the same class. Top-level imports work for both: from praisonai import SandboxedAgent, SandboxedAgentConfig and the legacy LocalManagedAgent/LocalManagedConfig.
• Rationale from PR: "tools sandboxed, loop local" — old name implied the whole loop was managed locally, which was misleading.

2. New ManagedRuntimeProtocol (Core SDK)

• Source: src/praisonai-agents/praisonaiagents/managed/protocols.py
• Exported from praisonaiagents.managed.
• Distinct from the existing ManagedBackendProtocol:
  • ManagedBackendProtocol → local agent loop, remote tool execution only (today's sandboxed model).
  • ManagedRuntimeProtocol → remote agent loop, full CRUD + event streaming (Anthropic Managed Agents, future E2B/Modal managed runtimes).
• Methods: create_agent, create_environment, create_session, send_event, stream_events (async generator), interrupt, retrieve_session, list_sessions, archive_session, delete_session.
• Lifecycle example (from the docstring):

  runtime = AnthropicManagedAgent(config=cfg)
  agent_id = await runtime.create_agent(config)
  env_id = await runtime.create_environment(config)
  session_id = await runtime.create_session(agent_id, env_id)
  
  await runtime.send_event(session_id, {"type": "user.message", "content": [...]})
  async for event in runtime.stream_events(session_id):
      if event["type"] == "agent.message":
          print(event["content"])

3. New typed configuration classes

Source: src/praisonai/praisonai/integrations/managed_agents.py

NetworkingConfig (replaces the untyped networking dict):

• type: NetworkingType — enum: UNRESTRICTED, LIMITED
• allowed_hosts: Optional[List[str]]
• allow_mcp_servers: bool = True
• allow_package_managers: bool = True

PackagesConfig (replaces the untyped packages dict):

• Fields for all 6 package managers: pip, npm, apt, cargo, gem, go (all Optional[List[str]]).
• Has .to_dict() for Anthropic API serialization.

Both are still backward compatible — ManagedConfig.networking and ManagedConfig.packages now accept Union[Dict, <TypedConfig>].

4. New VaultManager (OAuth credentials)

• Source: src/praisonai/praisonai/integrations/managed_agents.py
• Accessed via AnthropicManagedAgent.vaults (lazy property).
• Methods: create(provider, credentials, name=None), list(), retrieve(vault_id), delete(vault_id).
• Backed by client.beta.vaults.*.
• Example:

  managed = AnthropicManagedAgent(config=cfg)
  vault_id = managed.vaults.create("github", {"access_token": "ghp_..."})
  vaults = managed.vaults.list()
  managed.vaults.delete(vault_id)

5. New Agent / Environment / Session CRUD methods on AnthropicManagedAgent

Filling the Anthropic API gaps called out in the PR:

Agent API

• retrieve_agent() -> Dict
• list_agents(**kwargs) -> List[Dict]
• archive_agent() -> None (clears cached agent_id, agent_version, _session_id)
• list_agent_versions() -> List[Dict]

Environment API

• retrieve_environment() -> Dict
• list_environments(**kwargs) -> List[Dict]
• archive_environment() -> None
• delete_environment() -> None

Session API

• archive_session(session_id=None) -> None
• delete_session(session_id=None) -> None
• Session creation now supports agent version pinning — if self.agent_version is set, create_session passes agent={"type": "agent", "id": ..., "version": ...} instead of a bare ID.

6. New description field on ManagedConfig

• description: str = "" — forwarded to client.beta.agents.create(description=...) when non-empty.

Documentation work to be done

A. New pages (create in docs/features/ — agent-authorable)

1. docs/features/sandboxed-agent.mdx

   • Agent-centric quick start using SandboxedAgent/SandboxedAgentConfig (import from praisonai, not the internal module path).
   • Explain "tools sandboxed, loop local" clearly (diagram).
   • Document backward-compat: LocalManagedAgent and SandboxedAgent are the same class.
   • Cross-link to concepts/managed-agents-local (until that page is renamed by a human).

2. docs/features/managed-runtime-protocol.mdx

   • Introduce the new two-protocol model with a decision-tree Mermaid diagram:
     • ManagedBackendProtocol — use when tools need sandboxing but the loop stays local.
     • ManagedRuntimeProtocol — use when the whole loop runs on a provider (Anthropic Managed Agents, future E2B/Modal managed runtimes).
   • Show the full lifecycle example from the PR docstring (create_agent → create_environment → create_session → send_event → stream_events).
   • Document every method on the protocol (signature, args, return type) pulled directly from praisonaiagents/managed/protocols.py.

3. docs/features/managed-networking-config.mdx (or combine with packages into docs/features/managed-typed-configs.mdx)

   • NetworkingConfig + NetworkingType enum. Show unrestricted vs limited examples (allowed_hosts, allow_mcp_servers, allow_package_managers).
   • PackagesConfig for all 6 package managers with .to_dict() behaviour.
   • Show dict-form still works (backward compat).

4. docs/features/managed-vault.mdx

   • Agent-centric quick start for storing OAuth credentials via managed.vaults.*.
   • Table of provider/credential shapes (github access_token, slack access_token, etc.).
   • Security note: retrieve never returns credentials — only metadata.

5. docs/features/managed-agent-lifecycle.mdx (agent / environment / session CRUD)

   • Cover all new CRUD methods (retrieve_*, list_*, archive_*, delete_*).
   • Document agent version pinning (agent_version on the config → create_session behaviour).
   • Include a state-clearing note: archive_agent clears agent_id, agent_version, _session_id; archive_environment/delete_environment clears environment_id, _session_id.

B. Updates to existing pages — HUMAN APPROVAL REQUIRED (do not auto-edit)

Flag the following for human review. These are in docs/concepts/ and must not be modified by AI agents without explicit approval:

1. docs/concepts/managed-agents.mdx

   • Configuration Options table lists packages as Dict[str, List[str]] and networking as Dict[str, Any]. Should now show Union[Dict, PackagesConfig] / Union[Dict, NetworkingConfig] with a link to the new typed-configs page.
   • Add description field to the fields table.
   • Add a new "Two Protocols" section pointing at the managed-runtime-protocol feature page.

2. docs/concepts/managed-agents-local.mdx

   • Title / sidebar / references should be updated to reflect the SandboxedAgent naming. Options:
     • (a) Rename file to managed-agents-sandboxed.mdx and update docs.json (concepts group at lines 98–106).
     • (b) Keep the file, add a prominent "Now called SandboxedAgent" banner at the top, update code samples to use the new name, keep the old name visible for backward compat.
   • Human decision needed on which option.
   • All quick-start examples should be updated to the new names (old names remain valid as aliases).

C. docs.json updates

• Add the new feature pages listed in section A under the existing "Features" group that already contains managed-agent-persistence, managed-agents-session-info, managed-cli (lines 663–665).
• If the concepts page is renamed per B.2(a), update lines 101–106.

D. SDK reference pages

The auto-generated SDK reference may need to be regenerated to pick up:

• praisonaiagents.managed.protocols.ManagedRuntimeProtocol
• praisonai.integrations.managed_agents.NetworkingConfig, NetworkingType, PackagesConfig, VaultManager
• New methods on AnthropicManagedAgent

Per AGENTS.md section 1.7, these are auto-managed — run:

python3 src/praisonai/scripts/generate_docs_parity.py --copy-docs

from praisonai-package to regenerate parity reports and copy into docs/features/, docs/js/, docs/rust/.

Acceptance criteria

• docs/features/sandboxed-agent.mdx created (agent-centric quick start, uses from praisonai import SandboxedAgent, SandboxedAgentConfig, mentions backward compat).
• docs/features/managed-runtime-protocol.mdx created with decision-tree diagram and full lifecycle example.
• docs/features/managed-typed-configs.mdx (or two separate pages) covers NetworkingConfig, NetworkingType, PackagesConfig.
• docs/features/managed-vault.mdx created with VaultManager usage.
• docs/features/managed-agent-lifecycle.mdx created covering new agent/environment/session CRUD methods and agent version pinning.
• docs.json updated to register the new feature pages in the existing Features group (never Concepts).
• Each new page follows the AGENTS.md template: frontmatter (title/sidebarTitle/description/icon), hero Mermaid with the standard color scheme, Quick Start <Steps>, Common Patterns, Best Practices <AccordionGroup>, Related <CardGroup>.
• Every code example uses the user-facing top-level imports (from praisonai import ..., from praisonaiagents import Agent), not internal module paths, and runs copy-paste.
• Types / defaults in every options table match the SDK source (protocols.py, managed_agents.py) exactly — no guessing.
• Concept pages under docs/concepts/ are NOT modified by the implementing agent. Instead, a PR comment or follow-up issue flags the two updates in section B for human review.

Reference source files (ground truth)

Triggered by webhook on pull_request.closed (merged) for PR #1526.