> ## 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.
# 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.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Local Managed Agent"
A[📝 Request] --> B[🧠 Local LLM]
B --> C[💻 Local Tools]
C --> D[📁 Local Storage]
D --> E[✅ Response]
end
classDef request fill:#6366F1,stroke:#7C90A0,color:#fff
classDef llm fill:#8B0000,stroke:#7C90A0,color:#fff
classDef tools fill:#189AB4,stroke:#7C90A0,color:#fff
classDef storage fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef response fill:#10B981,stroke:#7C90A0,color:#fff
class A request
class B llm
class C tools
class D storage
class E response
```
## Quick Start
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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)
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant LocalManaged
participant LocalLLM
participant LocalFS
User->>Agent: Request
Agent->>LocalManaged: Execute
LocalManaged->>LocalLLM: Process
LocalLLM-->>LocalManaged: Response
LocalManaged->>LocalFS: Save Session
LocalManaged-->>Agent: Result
Agent-->>User: Output
```
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.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
A[📦 Package Request] --> B{Compute Provider?}
B -->|Yes| C[🐳 Install in Sandbox]
B -->|No| D{host_packages_ok?}
D -->|True| E[⚠️ Install on Host]
D -->|False| F[🚫 Raise ManagedSandboxRequired]
C --> G[✅ Secure]
E --> H[⚠️ Development Only]
F --> I[❌ Error]
classDef secure fill:#10B981,stroke:#7C90A0,color:#fff
classDef warning fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef error fill:#8B0000,stroke:#7C90A0,color:#fff
classDef decision fill:#189AB4,stroke:#7C90A0,color:#fff
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
class A input
class B,D decision
class C,G secure
class E,H warning
class F,I error
```
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
Setting `host_packages_ok=True` installs packages directly on your host system, which can create security risks. Only use this in trusted developer environments where you control the package sources.
***
## Compute Tool Bridging
When a compute provider is attached, four shell-based tools automatically execute inside the compute instance instead of on the host:
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant Agent
participant LocalManagedAgent
participant Compute
participant Result
Agent->>LocalManagedAgent: execute_command("ls")
LocalManagedAgent->>Compute: Bridge to compute.execute()
Compute-->>LocalManagedAgent: Command output
LocalManagedAgent-->>Agent: Bridged result
Note over LocalManagedAgent,Compute: Also bridges: read_file, write_file, list_files
```
Bridged tools: `execute_command`, `read_file`, `write_file`, `list_files`
***
## Configuration Options
### LocalManagedConfig Fields
| Option | Type | Default | Description |
| ------------------ | ---------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `model` | `str` | `"gpt-4o"` | LLM model to use |
| `system` | `str` | `"You are a helpful coding assistant."` | System prompt |
| `name` | `str` | `"Agent"` | Agent display name |
| `tools` | `List[str]` | Default tools | Enabled tool names |
| `packages` | `Dict[str, List[str]]` | `None` | Packages to install (e.g. `{"pip": ["pandas"]}`) |
| `networking` | `Dict[str, Any]` | `{"type": "unrestricted"}` | Network access policy |
| `host_packages_ok` | `bool` | `False` | Security opt-out. When `True`, permits pip install on host when no compute provider is attached |
| `working_dir` | `str` | `""` | Working directory inside the sandbox |
| `env` | `Dict[str, str]` | `{}` | Extra environment variables |
***
## Session Management
### Persistent Sessions
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```
`retrieve_session()` **always** returns all 4 keys (`id`, `status`, `title`, `usage`) with sensible defaults when no session exists.
### Resume Sessions
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
Use compute providers like `compute="docker"` for package installation. Only set `host_packages_ok=True` in trusted developer environments. Packages require a sandbox by default to prevent security risks.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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}")
```
Save session IDs using `save_ids()` for resuming conversations. Store IDs in a database or file system for persistence across application restarts.
Only enable tools your agent needs. When using compute providers, shell tools automatically execute in the sandbox for security.
***
## Related
Overview of managed agent concepts
Containerized execution environments
Unified session schema reference