> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Managed Agents

> Run agents on cloud infrastructure with automatic provisioning and management

Managed Agents run on cloud infrastructure, automatically provisioning compute resources and managing execution environments.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Managed Agents Flow"
        A[📝 Request] --> B[☁️ Cloud Agent]
        B --> C[🛠️ Compute Environment]
        C --> D[📋 Execution]
        D --> E[✅ Results]
    end
    
    classDef request fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef cloud fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef compute fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef execution fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff
    
    class A request
    class B cloud
    class C compute
    class D execution
    class E result
```

## Quick Start

<Steps>
  <Step title="Basic Usage">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent
    from praisonai.integrations.managed_agents import ManagedAgent

    agent = Agent(name="teacher", backend=ManagedAgent())
    result = agent.start("Write a Python script that prints Hello World and run it")
    print(result)
    ```
  </Step>

  <Step title="With Configuration">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent
    from praisonai.integrations.managed_agents import ManagedAgent, ManagedConfig

    managed = ManagedAgent(
        config=ManagedConfig(
            model="claude-sonnet-4-6",
            system="You are a helpful assistant. Be concise.",
            name="MyAgent",
            packages={"pip": ["pandas", "numpy"]},
        ),
        compute="docker"  # required for package installation
    )
    agent = Agent(name="data-analyst", backend=managed)
    result = agent.start("Analyze this data: [1,2,3,4,5]", stream=True)
    ```
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant ManagedAgent
    participant Cloud
    
    User->>Agent: Request
    Agent->>ManagedAgent: Execute
    ManagedAgent->>Cloud: Provision Environment
    Cloud-->>ManagedAgent: Environment Ready
    ManagedAgent->>Cloud: Run Code
    Cloud-->>ManagedAgent: Results
    ManagedAgent-->>Agent: Response
    Agent-->>User: Final Output
```

### Security Model

Managed agents enforce sandbox-first security by default. Package installation requires a compute provider or explicit opt-out to prevent host system security risks.

* **Compute-bridged tools**: `execute_command`, `read_file`, `write_file`, `list_files` automatically execute in sandbox when compute provider is attached
* **ManagedSandboxRequired**: Exception raised when packages are specified without proper sandboxing (see [Local Provider security details](/docs/concepts/managed-agents-local#security-sandboxed-package-installation))

| Component            | Purpose                     | Managed By     |
| -------------------- | --------------------------- | -------------- |
| **Agent Definition** | Model, system prompt, tools | Cloud Provider |
| **Environment**      | Compute resources, packages | Cloud Provider |
| **Session**          | Conversation context, state | Cloud Provider |
| **Execution**        | Code running, tool usage    | Cloud Provider |

***

## Compute Providers

Managed Agents support multiple compute providers for different use cases:

<CardGroup cols={2}>
  <Card title="Local Provider" icon="desktop" href="/docs/concepts/managed-agents-local">
    Run on local infrastructure with cloud management
  </Card>

  <Card title="Docker Compute" icon="docker" href="/docs/concepts/managed-agents-docker">
    Containerized execution environments
  </Card>

  <Card title="E2B Cloud" icon="cloud-bolt" href="/docs/concepts/managed-agents-e2b">
    Instant cloud sandboxes for code execution
  </Card>

  <Card title="Modal Compute" icon="server" href="/docs/concepts/managed-agents-modal">
    Serverless compute for scalable workloads
  </Card>

  <Card title="Daytona Workspaces" icon="code" href="/docs/concepts/managed-agents-daytona">
    Development environments with persistent storage
  </Card>
</CardGroup>

***

## Configuration Options

<Card title="ManagedConfig API Reference" icon="code" href="/docs/sdk/reference/typescript/classes/ManagedConfig">
  Complete configuration options for managed agents
</Card>

### Key Configuration Fields

| Option       | Type                   | Default                                 | Description                                                                                                                                                      |
| ------------ | ---------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`      | `str`                  | `"claude-haiku-4-5"`                    | LLM model to use                                                                                                                                                 |
| `system`     | `str`                  | `"You are a helpful coding assistant."` | System prompt                                                                                                                                                    |
| `tools`      | `List[Dict]`           | `[{"type": "agent_toolset_20260401"}]`  | Available tools                                                                                                                                                  |
| `packages`   | `Dict[str, List[str]]` | `None`                                  | Package dependencies. **Requires compute provider** by default ([security details](/docs/concepts/managed-agents-local#security-sandboxed-package-installation)) |
| `networking` | `Dict[str, Any]`       | `{"type": "unrestricted"}`              | Network access policy                                                                                                                                            |

### Custom Backend Development

Build a custom managed backend by implementing the protocol:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Build a custom managed backend by implementing this protocol
from praisonaiagents.managed import ManagedBackendProtocol
```

***

## Common Patterns

### Environment with Packages

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonai.integrations.managed_agents import ManagedAgent, ManagedConfig

managed = ManagedAgent(
    config=ManagedConfig(
        model="claude-sonnet-4-6",
        packages={
            "pip": ["pandas", "matplotlib", "requests"],
            "npm": ["@types/node", "axios"]
        },
        networking={"type": "limited"}
    ),
    compute="docker"  # required for secure package installation
)
agent = Agent(name="data-scientist", backend=managed)
```

### Session Persistence

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Save session state
managed = ManagedAgent(config=config)
agent = Agent(name="persistent", backend=managed)
agent.start("Remember: my favorite color is blue")
ids = managed.save_ids()

# Resume in another process
managed2 = ManagedAgent(config=config)
managed2.restore_ids(ids)
managed2.resume_session(ids["session_id"])
agent2 = Agent(name="resumed", backend=managed2)
result = agent2.start("What is my favorite color?")  # Knows: blue
```

### Custom Tools

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
def handle_calculator(tool_name, tool_input):
    expr = tool_input.get("expression", "0")
    return str(eval(expr, {"__builtins__": {}}))

managed = ManagedAgent(
    config=ManagedConfig(
        tools=[{
            "type": "custom",
            "name": "calculator",
            "description": "Evaluate math expressions",
            "input_schema": {
                "type": "object",
                "properties": {"expression": {"type": "string"}},
                "required": ["expression"]
            }
        }]
    ),
    on_custom_tool=handle_calculator
)
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Choose the Right Compute Provider">
    * **Local**: Development and testing with existing infrastructure
    * **Docker**: Isolated, reproducible environments
    * **E2B**: Quick prototyping and sandboxed execution
    * **Modal**: High-performance, scalable workloads
    * **Daytona**: Development environments with persistence
  </Accordion>

  <Accordion title="Manage Sessions Effectively">
    Save session IDs for resuming conversations across process restarts. Use `save_ids()` and `restore_ids()` to maintain context between runs.
  </Accordion>

  <Accordion title="Configure Security Appropriately">
    Use `networking: {"type": "limited"}` for untrusted code execution. Enable only required packages to minimize attack surface. The new `host_packages_ok` flag and `ManagedSandboxRequired` exception provide additional security controls - see [Local Provider security details](/docs/concepts/managed-agents-local#security-sandboxed-package-installation).
  </Accordion>

  <Accordion title="Monitor Resource Usage">
    Track token usage with `retrieve_session()` — returns a unified schema (`id`, `status`, `title`, `usage`) on all backends. See the [SessionInfo Schema page](/docs/features/managed-agents-session-info) for details.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Agents" icon="user" href="/docs/concepts/agents">
    Core agent concepts and configuration
  </Card>

  <Card title="Tools" icon="wrench" href="/docs/concepts/tools">
    Available tools and custom tool creation
  </Card>
</CardGroup>