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.

Quick Start

1. Basic Usage

   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)
   
2. With Configuration

   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)
   

---

How It Works

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)

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:

Local Provider

Run on local infrastructure with cloud management

Docker Compute

Containerized execution environments

E2B Cloud

Instant cloud sandboxes for code execution

Modal Compute

Serverless compute for scalable workloads

Daytona Workspaces

Development environments with persistent storage

---

Configuration Options

ManagedConfig API Reference

Complete configuration options for managed agents

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)
networking	Dict[str, Any]	{"type": "unrestricted"}	Network access policy

Custom Backend Development

Build a custom managed backend by implementing the protocol:

# Build a custom managed backend by implementing this protocol
from praisonaiagents.managed import ManagedBackendProtocol

---

Common Patterns

Environment with Packages

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

# 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

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

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

Manage Sessions Effectively

Save session IDs for resuming conversations across process restarts. Use save_ids() and restore_ids() to maintain context between runs.

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.

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 for details.

---

Related

Agents

Core agent concepts and configuration

Tools

Available tools and custom tool creation