Context

Tracks documentation work for the SDK change in MervinPraison/PraisonAI#1550 ("fix: ManagedAgent provider overload conflates hosted-runtime vs LLM-routing"). The PR landed on main and introduces two new canonical agent backends (HostedAgent, LocalAgent) and deprecates the overloaded ManagedAgent(provider=...) factory pattern.

This issue requires both new content and updates to existing pages. See sections below.

SDK Change Summary (ground truth — read before writing docs)

The PR adds these files in praisonai-package/src/praisonai/:

• praisonai/integrations/hosted_agent.py — new HostedAgent + HostedAgentConfig
• praisonai/integrations/local_agent.py — new LocalAgent + LocalAgentConfig
• praisonai/integrations/managed_agents.py — ManagedAgent factory updated with deprecation warnings + provider routing
• praisonai/__init__.py and praisonai/integrations/__init__.py — top-level exports for the new classes
• examples/python/managed-agents/provider/ — new canonical examples (runtime_hosted_anthropic.py, runtime_local_openai.py, runtime_local_gemini.py, runtime_local_ollama.py)
• tests/unit/integrations/test_backend_semantics.py — tests covering all semantic requirements

⚠️ Mandatory before writing any page: Open the actual SDK source files above and verify every parameter, type, and default. Do not paraphrase from this issue — the issue is a starting brief, the SDK is the source of truth.

Two new canonical classes

Imports (verify against praisonai/__init__.py and praisonai/integrations/__init__.py)

# Top-level (preferred for users)
from praisonai import HostedAgent, HostedAgentConfig, LocalAgent, LocalAgentConfig

# Or via integrations
from praisonai.integrations import HostedAgent, HostedAgentConfig, LocalAgent, LocalAgentConfig

# Agent itself
from praisonaiagents import Agent

Class signatures (verify in source — do not blindly copy)

# hosted_agent.py
HostedAgentConfig = ManagedConfig  # alias of existing ManagedConfig

class HostedAgent(AnthropicManagedAgent):
    def __init__(
        self,
        provider: str = "anthropic",
        config: Optional[Any] = None,
        **kwargs,
    ):
        # Raises ValueError if provider != "anthropic" with helpful migration hint

# local_agent.py
LocalAgentConfig = LocalManagedConfig  # alias of existing LocalManagedConfig

class LocalAgent(LocalManagedAgent):
    def __init__(
        self,
        compute: Optional[Any] = None,   # "e2b" | "modal" | "flyio" | "daytona" | "docker" | None
        config: Optional[Any] = None,
        **kwargs,
    ):
        # If provider= is passed, emits DeprecationWarning but routes through for back-compat

ManagedAgent factory behaviour after PR (deprecation matrix)

Verify against the actual ManagedAgent() factory in managed_agents.py lines around 1075–1145.

Documentation Work Required

Folder placement (per AGENTS.md)

All new and updated files go under docs/features/. Do NOT touch docs/concepts/ (human-only). Do not edit auto-generated docs/js/ or docs/rust/.

Two NEW pages to create

1. docs/features/hosted-agent.mdx (new)

Page for the HostedAgent class. Required sections per AGENTS.md template:

• Frontmatter — title: "Hosted Agent", sidebarTitle: "Hosted Agent", description: "Run the entire agent loop on Anthropic's managed cloud runtime", icon: "cloud".
• One-sentence intro — what it does (entire loop in Anthropic's cloud), not how.
• Hero Mermaid diagram — graph LR showing User → HostedAgent → Anthropic cloud → tools running there → response. Use the standard color palette (#8B0000, #189AB4, #10B981, #F59E0B, #6366F1, white text, #7C90A0 strokes).
• Quick Start — <Steps> with two <Step>s:
  1. Simple Usage — minimal HostedAgent(provider="anthropic", config=HostedAgentConfig(model="claude-3-5-sonnet-latest", system="...")) wrapped in an Agent(name=..., backend=hosted). Show agent.start("...").
  2. With Tools and Multi-Turn — show tools=[{"type": "agent_toolset_20260401"}] and a second agent.start() call to demonstrate session continuity. Mirror examples/python/managed-agents/provider/runtime_hosted_anthropic.py from the SDK PR.
• How It Works — sequenceDiagram showing User → Agent → HostedAgent → Anthropic Cloud (loop + tools + LLM all on the right side) → response.
• When to Use HostedAgent vs LocalAgent — graph TB decision diagram (the user said: "If multiple options in one page, people might be confused on what to choose, so create the mermaid diagram to choose what option at what instance").
• Configuration Options — link to auto-generated SDK reference cards (/docs/sdk/reference/typescript/classes/HostedAgentConfig etc.) plus a small table of the most user-relevant fields (model, system, name, tools). Verify by reading ManagedConfig (which HostedAgentConfig aliases).
• Common Patterns:
  • Multi-turn conversation in the same session (Anthropic keeps state in the cloud).
  • Usage tracking via hosted.retrieve_session() (returns the unified SessionInfo shape — link to managed-agents-session-info).
  • Listing sessions via hosted.list_sessions().
• Migrating from ManagedAgent — short section showing the before/after:

  # Before
  ManagedAgent(provider="anthropic", config=ManagedConfig(...))
  # After
  HostedAgent(provider="anthropic", config=HostedAgentConfig(...))

• Best Practices — <AccordionGroup> with 3–4 entries (managing API costs, choosing tools, session reuse, error handling around the not yet available ValueError for non-Anthropic providers).
• Related — <CardGroup cols={2}> linking to local-agent, managed-agent-persistence, managed-agents-session-info, managed-cli.

2. docs/features/local-agent.mdx (new)

Page for the LocalAgent class. Required sections:

• Frontmatter — title: "Local Agent", sidebarTitle: "Local Agent", description: "Run the agent loop locally with any LLM and optional cloud-sandboxed tools", icon: "desktop".
• One-sentence intro — agent loop runs locally; LLM choice via config.model; optional compute= for cloud tool sandboxing.
• Hero Mermaid diagram — graph LR showing local Python process containing the agent loop, LLM call going out (any provider via litellm routing), and tools either local-subprocess or in cloud compute. Standard palette.
• Quick Start — <Steps>:
  1. Simplest — LocalAgent(config=LocalAgentConfig(model="gpt-4o-mini")) + Agent(backend=local).
  2. With Cloud Compute Sandbox — LocalAgent(compute="e2b", config=LocalAgentConfig(model="gpt-4o-mini", tools=["execute_command", "read_file", "write_file"])).
• How It Works — sequenceDiagram showing the local loop, LLM HTTP call (OpenAI/Gemini/Ollama via litellm prefixes), and tool execution either locally or routed to E2B/Modal/etc.
• Choosing an LLM — <Tabs> with one tab per provider (OpenAI, Gemini, Ollama, Anthropic-via-LLM-only, custom litellm prefix). Each tab shows the model= string. Mirror examples/python/managed-agents/provider/runtime_local_*.py files added in the PR.
• Choosing a Compute Backend — <Tabs> for None (local subprocess), "docker", "e2b", "modal", "flyio", "daytona". Each tab shows the one-line change. Plus a graph TB decision diagram for "which compute do I pick".
• Configuration Options — link to auto-generated reference for LocalAgentConfig (alias of LocalManagedConfig). Show only the user-relevant fields in a table.
• Common Patterns:
  • Switching LLMs without touching the rest of the code (just change model=).
  • Tool execution and tools=[...] parameter.
  • Multi-turn conversation with locally-maintained session state.
  • Usage tracking via local.retrieve_session().
• Migrating from ManagedAgent — table covering each old pattern → new pattern:

  Old	New
  ManagedAgent(provider="openai", config=LocalManagedConfig(model="gpt-4o"))	LocalAgent(config=LocalAgentConfig(model="gpt-4o"))
  ManagedAgent(provider="ollama", config=LocalManagedConfig(model="llama3"))	LocalAgent(config=LocalAgentConfig(model="ollama/llama3"))
  ManagedAgent(provider="gemini", ...)	LocalAgent(config=LocalAgentConfig(model="gemini/gemini-2.0-flash"))
  ManagedAgent(provider="e2b", ...)	LocalAgent(compute="e2b", config=LocalAgentConfig(...))
  ManagedAgent(provider="modal", ...)	LocalAgent(compute="modal", config=LocalAgentConfig(...))

• Best Practices — <AccordionGroup> (pick a compute backend matching your trust level, use litellm prefixes, prefer LocalAgent over the deprecated factory, avoid provider= kwarg).
• Related — links to hosted-agent, sandbox, managed-agent-persistence.

Existing pages to update

3. docs/features/managed-agent-persistence.mdx — UPDATE

This page currently uses ManagedAgent(provider="anthropic", ...) everywhere.

• Add a <Note> callout near the top: "ManagedAgent is deprecated as of PR #1550. New code should use HostedAgent for Anthropic-hosted runs (this page) or LocalAgent for local loops. Existing imports continue to work but emit a DeprecationWarning for non-Anthropic providers."
• Update every code example to use HostedAgent + HostedAgentConfig instead of ManagedAgent(provider="anthropic", config=ManagedConfig(...)). Imports become:

  from praisonai.integrations import HostedAgent, HostedAgentConfig

• Keep all the database-backend tabs (SQLite, PostgreSQL, MySQL, Redis, MongoDB, ClickHouse, JSON Files) — only the agent backend changes.
• Update the ## Configuration Options table heading from "ManagedAgent API Reference" to "HostedAgent API Reference" and update card hrefs to /docs/sdk/reference/typescript/classes/HostedAgent and /docs/sdk/reference/typescript/classes/HostedAgentConfig.
• Update the existing sequence diagram label from ManagedAgent → HostedAgent.
• Update the ## Related cards to also link to the new local-agent.mdx and hosted-agent.mdx pages.
• Optional rename consideration: if the site naming convention prefers it, this page can be renamed to hosted-agent-persistence.mdx. Default: keep the file name and slug to avoid breaking external links — only update the content. If renaming, add the old slug to docs.json redirects.

4. docs/features/managed-agents-session-info.mdx — UPDATE

• Add a <Note> at the top: the unified retrieve_session() shape applies to both HostedAgent and LocalAgent (the new canonical classes), as well as the deprecated ManagedAgent factory.
• Replace the Quick Start examples to use HostedAgent (anthropic) and LocalAgent (local) — drop ManagedAgent from the Quick Start. Keep the schema content unchanged.
• Update the ## Related cards to point at /docs/features/hosted-agent and /docs/features/local-agent (currently they point at /docs/concepts/managed-agents and /docs/concepts/managed-agents-local which appear not to exist — verify and fix the dead links while you're there).

5. docs/features/managed-cli.mdx — UPDATE (light)

• Update the "Related" <CardGroup> to add a card linking to the new hosted-agent.mdx page (the CLI manages Anthropic-hosted resources, so HostedAgent is the relevant Python-side counterpart).
• In the agents create row, change "See ManagedAgent docs" → "See HostedAgent docs" with a link to /docs/features/hosted-agent.

Navigation/sidebar update

6. docs.json — UPDATE

Add the two new pages under the Features group (per AGENTS.md rule: "Update docs.json to add pages under 'Features' group, NEVER under 'Concepts'"). Suggested placement: keep them adjacent to the existing managed-agent entries so users find them together. The exact entries should be:

"docs/features/hosted-agent",
"docs/features/local-agent",

After modification, validate docs.json is still valid JSON.

Examples to mirror

The PR adds runnable examples that should be adapted (shortened to "minimal way to do X") for the docs:

• examples/python/managed-agents/provider/runtime_hosted_anthropic.py → hosted-agent.mdx Quick Start.
• examples/python/managed-agents/provider/runtime_local_openai.py → local-agent.mdx OpenAI tab.
• examples/python/managed-agents/provider/runtime_local_gemini.py → local-agent.mdx Gemini tab.
• examples/python/managed-agents/provider/runtime_local_ollama.py → local-agent.mdx Ollama tab.
• examples/python/managed-agents/provider/all_providers.py (modified in PR) → local-agent.mdx Compute Backends tabs.
• examples/python/managed-agents/provider/local_basic.py (modified in PR) → local-agent.mdx simplest Quick Start.

Each example in the docs must be the shortest copy-paste-runnable form (per AGENTS.md writing rules). Strip print debug statements that aren't required to demonstrate the concept.

User Interaction Flow (per AGENTS.md rule 11)

Both pages must show, near the top, a real user interaction flow. Suggested:

• HostedAgent page: a developer wires HostedAgent into an existing Agent, calls agent.start("..."), gets a streamed response, asks a follow-up that uses session continuity, then calls hosted.retrieve_session() to log usage.
• LocalAgent page: a developer picks an LLM via model=, calls agent.start("..."), and (in a second step) flips to compute="e2b" to sandbox tool execution without changing any other line.

Constraints & Guard-Rails (from AGENTS.md)

The implementing agent must:

• Read the actual SDK source for every parameter before writing — do not copy this issue verbatim.
• Place new files under docs/features/ only. Do not touch docs/concepts/.
• Never edit docs/js/ or docs/rust/ (auto-generated).
• Use Mintlify components (<Steps>, <AccordionGroup>, <CardGroup>, <Tabs>).
• Include a hero Mermaid diagram on every page using the standard color palette (#8B0000, #189AB4, #10B981, #F59E0B, #6366F1; white text; #7C90A0 strokes).
• Default to no comments in code examples; use realistic but minimal data; never use placeholder secrets like "your-key-here".
• Use simple imports (from praisonai import ..., from praisonai.integrations import ..., from praisonaiagents import Agent) — no deep paths in user-facing examples.
• Page tone: non-developer-friendly, agent-centric (top-of-page example must use Agent(...)), make the reader feel "is it really this easy?"
• One-sentence section intros. No forbidden phrases ("In this section…", "As you can see…", "Please note that…", "Let's take a look at…", "The following example shows…", "It's important to note that…").
• Active voice. Direct.
• After writing, validate docs.json is valid JSON.
• Open a PR (never push directly to main). Use a feature branch.

Suggested PR Title

docs(features): add HostedAgent + LocalAgent pages, update ManagedAgent references

Acceptance Checklist

• docs/features/hosted-agent.mdx created, follows AGENTS.md template, runs cleanly when previewed.
• docs/features/local-agent.mdx created, follows AGENTS.md template, runs cleanly when previewed.
• docs/features/managed-agent-persistence.mdx updated to use HostedAgent, deprecation note added, dead Related links fixed.
• docs/features/managed-agents-session-info.mdx updated to reference HostedAgent/LocalAgent, broken Related links fixed.
• docs/features/managed-cli.mdx updated with link to the new hosted-agent.mdx.
• docs.json includes both new pages in the Features group, file is valid JSON.
• All code examples in updated/new pages are minimal, copy-pasteable, and use the canonical imports.
• All Mermaid diagrams use the standard color palette.
• No dead links to /docs/concepts/managed-agents* remain anywhere in the touched files.
• PR opened against main (do NOT modify docs/concepts/).

Reference Links

• SDK PR: fix: ManagedAgent provider overload conflates hosted-runtime vs LLM-routing PraisonAI#1550
• Originating issue: Fix: ManagedAgent(provider=) overload conflates hosted-runtime vs LLM-routing — propose HostedAgent / LocalAgent split PraisonAI#1549
• New SDK files (after merge):
  • praisonai-package/src/praisonai/praisonai/integrations/hosted_agent.py
  • praisonai-package/src/praisonai/praisonai/integrations/local_agent.py
  • praisonai-package/src/praisonai/praisonai/integrations/managed_agents.py (factory updated)
• New SDK examples: praisonai-package/src/praisonai/examples/python/managed-agents/provider/runtime_*.py
• Tests: praisonai-package/src/praisonai/tests/unit/integrations/test_backend_semantics.py