Local Managed Agents

Run managed agents on local infrastructure with cloud management APIs

Local managed agents provide cloud-style APIs while running on your local infrastructure.

Quick Start

1. Basic Local Agent

   from praisonaiagents import Agent
   from praisonai.integrations.managed_agents import ManagedAgent, ManagedConfig
   
   managed = ManagedAgent(
       provider="local",
       config=ManagedConfig(model="gpt-4o-mini")
   )
   agent = Agent(name="local-assistant", backend=managed)
   result = agent.start("What is the capital of France?", stream=True)

2. With Secure Package Installation

   from praisonaiagents import Agent
   from praisonai.integrations.managed_agents import ManagedAgent, ManagedConfig
   
   managed = ManagedAgent(
       provider="local",
       config=ManagedConfig(
           model="gpt-4o-mini",
           packages={"pip": ["pandas", "numpy"]},
       ),
       compute="docker",   # required when packages are specified
   )
   agent = Agent(name="analyst", backend=managed)
   result = agent.start("Analyze this data: [1,2,3,4,5]", stream=True)

How It Works

Local managed agents provide the same APIs as cloud providers while keeping data on your infrastructure.

Security: Sandboxed Package Installation

Local managed agents enforce sandbox-first security for package installation by default.

When packages are specified, three resolution paths exist:

1. Compute Provider (Recommended): Attach compute="docker" to install packages in a sandbox
2. Host Installation (Development Only): Set host_packages_ok=True for trusted environments
3. No Packages: Remove packages configuration to avoid installation

Compute Tool Bridging

When a compute provider is attached, four shell-based tools automatically execute inside the compute instance instead of on the host:

Bridged tools: execute_command, read_file, write_file, list_files

Tool Name Resolution

LocalManagedAgent resolves the strings in tools=[...] through the same canonical ToolResolver chain used by CLI --tools, YAML agents.yaml, recipes, and plain Agent(tools=[...]). A tool that resolves in one surface now resolves here too.

Resolution order (first match wins):

1. Local tools.py / tools/ folder (requires PRAISONAI_ALLOW_LOCAL_TOOLS=true)
2. Wrapper ToolRegistry (register_function, register_from_module)
3. praisonaiagents.tools built-ins (e.g. execute_command, read_file)
4. praisonai-tools package
5. Entry-point plugins (praisonai.tool_sources)

When praisonai-code is not installed, the backend falls back to the historical praisonaiagents.tools lookup, so existing configs keep working unchanged.

Anthropic-style tool configs ({"type": "agent_toolset_20260401", ...}) and TOOL_ALIAS_MAP normalisation still run before resolution — the resolver only ever sees canonical tool names. Compute-bridge wrapping (execute_command, read_file, write_file, list_files) still runs after resolution regardless of the resolved source, so shell-based tools continue to execute inside the compute instance when one is attached.

Configuration Options

LocalManagedConfig Fields

Session Management

Persistent Sessions

from praisonaiagents import Agent
from praisonai.integrations.managed_agents import ManagedAgent, ManagedConfig

# Create agent with session persistence
managed = ManagedAgent(
    provider="local",
    config=ManagedConfig(
        model="gpt-4o-mini",
        name="PersistentAgent"
    )
)
agent = Agent(name="persistent", backend=managed)

# First conversation
agent.start("Remember: my favorite color is blue")
session_info = managed.retrieve_session()
print(f"Session ID: {session_info['id']}")
print(f"Status: {session_info['status']}")

# Save session for later
ids = managed.save_ids()
# Store ids to file/database for persistence across restarts

Resume Sessions

# In another process/restart
managed2 = ManagedAgent(
    provider="local", 
    config=ManagedConfig(model="gpt-4o-mini")
)
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

Multi-turn Conversations

from praisonaiagents import Agent
from praisonai.integrations.managed_agents import ManagedAgent, ManagedConfig

managed = ManagedAgent(
    provider="local",
    config=ManagedConfig(
        model="gpt-4o-mini",
        system="You are a math tutor. Help students learn step by step.",
        name="MathTutor"
    )
)
agent = Agent(name="tutor", backend=managed)

# Multi-turn conversation in same session
response1 = agent.start("Explain what a derivative is", stream=True)
response2 = agent.start("Now show me how to find the derivative of x²", stream=True)
response3 = agent.start("What about x³?", stream=True)

# Session remembers all previous context

Usage Tracking

from praisonaiagents import Agent
from praisonai.integrations.managed_agents import ManagedAgent, ManagedConfig

managed = ManagedAgent(
    provider="local",
    config=ManagedConfig(model="gpt-4o-mini")
)
agent = Agent(name="tracker", backend=managed)

# Execute some tasks
agent.start("Write a short poem")
agent.start("Explain quantum physics briefly")

# Check usage
session_info = managed.retrieve_session()
print(f"Session: {session_info['id']} (status: {session_info['status']})")
print(f"Input tokens:  {session_info['usage']['input_tokens']}")
print(f"Output tokens: {session_info['usage']['output_tokens']}")

# Also available on instance
print(f"Total input: {managed.total_input_tokens}")
print(f"Total output: {managed.total_output_tokens}")

Best Practices

from praisonai.integrations.managed_agents import ManagedSandboxRequired
try:
    agent.start("Install pandas and analyze data")
except ManagedSandboxRequired as e:
    # Either attach a compute provider, or set host_packages_ok=True
    print(f"Security error: {e}")

Related