Local Agent - PraisonAI

LocalAgent runs the agent execution loop locally in your process, supporting any LLM via litellm routing and optional cloud compute for tool sandboxing.

from praisonai import LocalAgent, LocalAgentConfig
from praisonaiagents import Agent

local = LocalAgent(config=LocalAgentConfig(model="gpt-4o-mini"))
agent = Agent(name="assistant", backend=local)
agent.start("Explain quantum computing in simple terms")

The user sends a message; LocalAgent runs the loop on your machine and returns the model response.

Quick Start

Simplest Usage

Create a local agent with minimal configuration:

from praisonai import LocalAgent, LocalAgentConfig
from praisonaiagents import Agent

local = LocalAgent(
    config=LocalAgentConfig(
        model="gpt-4o-mini"
    )
)

agent = Agent(name="assistant", backend=local)
result = agent.start("Explain quantum computing in simple terms")

With Cloud Compute Sandbox

Use compute= to run tools in a cloud sandbox while thinking stays local:

from praisonai import LocalAgent, LocalAgentConfig
from praisonaiagents import Agent

local = LocalAgent(
    compute="e2b",  # Cloud sandbox for tools
    config=LocalAgentConfig(
        model="gpt-4o-mini",
        tools=["execute_command", "read_file", "write_file"]
    )
)

agent = Agent(name="coder", backend=local)
result = agent.start("Create a Python script that analyzes a CSV file")

LocalAgent uses compute= to place its tools on a provider. To share one sandbox across a whole flow or team, use AgentFlow(run_on=…). See Placement.

How It Works

Component	Location	Purpose
Agent Loop	Local Process	Complete execution control
LLM	External API	Any provider via litellm routing
Tools	Local or Cloud	Configurable execution environment
Session State	Local Memory	Process-managed state

Choosing an LLM

OpenAI
Gemini
Ollama
Anthropic
Custom

Use OpenAI models with API key authentication:

from praisonai import LocalAgent, LocalAgentConfig
import os

# Set via shell: export OPENAI_API_KEY="sk-..."

local = LocalAgent(
    config=LocalAgentConfig(
        model="gpt-4o"  # or "gpt-4o-mini", "gpt-3.5-turbo"
    )
)

Use Google’s Gemini models:

from praisonai import LocalAgent, LocalAgentConfig
import os

# Set via shell: export GOOGLE_API_KEY="AIza..."

local = LocalAgent(
    config=LocalAgentConfig(
        model="gemini/gemini-2.0-flash"  # litellm prefix required
    )
)

Use local Ollama models:

from praisonai import LocalAgent, LocalAgentConfig

# Requires Ollama running locally
local = LocalAgent(
    config=LocalAgentConfig(
        model="ollama/llama3"  # litellm prefix required
    )
)

Use Claude models via API:

from praisonai import LocalAgent, LocalAgentConfig
import os

# Set via shell: export ANTHROPIC_API_KEY="sk-ant-..."

local = LocalAgent(
    config=LocalAgentConfig(
        model="claude-3-5-sonnet-latest"
    )
)

Use any litellm-supported provider:

from praisonai import LocalAgent, LocalAgentConfig

local = LocalAgent(
    config=LocalAgentConfig(
        model="azure/gpt-4o"  # Azure OpenAI
        # model="groq/llama3-70b-8192"  # Groq
        # model="together_ai/meta-llama/Llama-2-70b-chat-hf"  # Together AI
    )
)

Choosing a Compute Backend

Execute tools in local subprocess (fastest, least secure):

from praisonai import LocalAgent, LocalAgentConfig

local = LocalAgent(
    # No compute parameter = local subprocess
    config=LocalAgentConfig(
        model="gpt-4o-mini",
        tools=["execute_command", "read_file", "write_file"]
    )
)

Local subprocess compute validates every packages={"pip": [...]} entry against a strict allowlist. Only PEP 508 requirement specifiers are accepted — name, extras, version bounds, and comments (characters A-Z a-z 0-9 . _ - [ ] < > = , ~ ! + and spaces).Pip options with a leading dash are rejected: --upgrade, --pre, -r requirements.txt, -e ./pkg. An invalid entry raises:

ValueError: Invalid pip package specifier: '--upgrade'. Only pip requirement specifiers are allowed.

Rewrite options as plain specifiers:

# Rejected
config = LocalAgentConfig(packages={"pip": ["--upgrade", "-r req.txt"]})

# Accepted
config = LocalAgentConfig(packages={"pip": ["pandas>=2", "numpy"]})

Execute tools in Docker containers:

from praisonai import LocalAgent, LocalAgentConfig

local = LocalAgent(
    compute="docker",
    config=LocalAgentConfig(
        model="gpt-4o-mini",
        tools=["execute_command", "read_file", "write_file"]
    )
)

Execute tools in E2B cloud sandboxes:

from praisonai import LocalAgent, LocalAgentConfig
import os

# Set via shell: export E2B_API_KEY="e2b_..."

local = LocalAgent(
    compute="e2b",
    config=LocalAgentConfig(
        model="gpt-4o-mini",
        tools=["execute_command", "read_file", "write_file"]
    )
)

Execute tools on Modal cloud compute:

from praisonai import LocalAgent, LocalAgentConfig
import os

# Set via shell: export MODAL_TOKEN="ak-..."

local = LocalAgent(
    compute="modal",
    config=LocalAgentConfig(
        model="gpt-4o-mini",
        tools=["execute_command", "read_file", "write_file"]
    )
)

Execute tools on Fly.io infrastructure:

from praisonai import LocalAgent, LocalAgentConfig
import os

# Set via shell: export FLY_API_TOKEN="fo1-..."

local = LocalAgent(
    compute="flyio",
    config=LocalAgentConfig(
        model="gpt-4o-mini",
        tools=["execute_command", "read_file", "write_file"]
    )
)

Execute tools in Daytona development environments:

from praisonai import LocalAgent, LocalAgentConfig
import os

# Set via shell: export DAYTONA_API_KEY="dtn-..."

local = LocalAgent(
    compute="daytona",
    config=LocalAgentConfig(
        model="gpt-4o-mini",
        tools=["execute_command", "read_file", "write_file"]
    )
)

Execute tools in Novita cloud sandboxes:

from praisonai import LocalAgent, LocalAgentConfig
import os

# Set via shell: export NOVITA_API_KEY="your-key"

local = LocalAgent(
    compute="novita",
    config=LocalAgentConfig(
        model="gpt-4o-mini",
        tools=["execute_command", "read_file", "write_file"]
    )
)

Compute Selection Guide

File-based defaults

Instead of passing image / packages / env as kwargs on every call, commit them to a .praisonai/environment.yaml. Every compute= backend loads it automatically; kwargs still win when provided.

Repo-committed .praisonai/environment.yaml — image, packages, setup, resources

The docker backend also caches the provisioned environment across runs — see Environment Capture.

Configuration Options

LocalAgent API Reference

Complete LocalAgent configuration options

LocalAgentConfig Reference

Configuration object parameters

Option	Type	Default	Description
`model`	`str`	Required	LLM model (supports litellm prefixes)
`system`	`str`	`"You are a helpful assistant."`	System prompt
`tools`	`List[str]`	`[]`	Available tool names
`packages`	`Dict`	`None`	Package dependencies for compute. PEP 508 requirement specifiers only; pip options such as `--upgrade` or `-r file` are rejected with `ValueError`
`host_packages_ok`	`bool`	`False`	Allow host package installation

Common Patterns

Switching LLMs

Change LLM providers without touching other code:

from praisonai import LocalAgent, LocalAgentConfig
from praisonaiagents import Agent

# Start with OpenAI
config = LocalAgentConfig(
    model="gpt-4o-mini",
    system="You are a helpful coding assistant."
)

# Switch to Gemini
config.model = "gemini/gemini-2.0-flash"

# Switch to Ollama
config.model = "ollama/llama3"

# Same agent setup works with any model
local = LocalAgent(config=config)
agent = Agent(name="coder", backend=local)

Tool Execution

Configure tools for different execution environments:

from praisonai import LocalAgent, LocalAgentConfig

# Local execution (fast, less secure)
local_tools = LocalAgent(
    config=LocalAgentConfig(
        model="gpt-4o-mini",
        tools=["read_file", "write_file", "execute_command"]
    )
)

# Cloud execution (slower, more secure)
cloud_tools = LocalAgent(
    compute="e2b",
    config=LocalAgentConfig(
        model="gpt-4o-mini", 
        tools=["read_file", "write_file", "execute_command"]
    )
)

Multi-turn Conversations

Maintain conversation state locally:

from praisonai import LocalAgent, LocalAgentConfig
from praisonaiagents import Agent

local = LocalAgent(
    config=LocalAgentConfig(
        model="gpt-4o-mini",
        system="You are a helpful assistant with memory."
    )
)

agent = Agent(name="assistant", backend=local)

# First turn
agent.start("My name is Alice")

# Second turn - state maintained in local process
response = agent.start("What's my name?")
# Response: "Your name is Alice"

Usage Tracking

Monitor local agent resource usage:

# After execution
session_info = local.retrieve_session()
print(f"Input tokens: {session_info['usage']['input_tokens']}")
print(f"Output tokens: {session_info['usage']['output_tokens']}")

# List sessions
sessions = local.list_sessions()
for session in sessions:
    print(f"Session: {session['id']}")

Multi-tenant safety

Two LocalAgent instances with different API keys stay isolated in the same process.

from praisonai import LocalAgent, LocalAgentConfig
from praisonaiagents import Agent

tenant_a = LocalAgent(
    api_key="sk-tenant-a",
    config=LocalAgentConfig(model="gpt-4o-mini")
)
tenant_b = LocalAgent(
    api_key="sk-tenant-b",
    config=LocalAgentConfig(model="gpt-4o-mini")
)

agent_a = Agent(name="tenant-a", backend=tenant_a)
agent_b = Agent(name="tenant-b", backend=tenant_b)

PraisonAI passes api_key and base_url directly to the inner agent, so credentials never leak into os.environ or a spawned subprocess. Each instance keeps its own key, even when many run in the same process.

Migrating from ManagedAgent

Update deprecated factory patterns to use the new canonical classes:

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", config=LocalManagedConfig(...))`	`LocalAgent(config=LocalAgentConfig(model="gemini/gemini-2.0-flash"))`
`ManagedAgent(provider="e2b", config=LocalManagedConfig(...))`	`LocalAgent(compute="e2b", config=LocalAgentConfig(...))`
`ManagedAgent(provider="modal", config=LocalManagedConfig(...))`	`LocalAgent(compute="modal", config=LocalAgentConfig(...))`
`ManagedAgent(provider="local", config=LocalManagedConfig(...))`	`LocalAgent(config=LocalAgentConfig(...))`

Best Practices

Compute Backend Selection

Choose compute backends based on your trust and security requirements:

Use local subprocess for development and trusted environments
Use Docker for moderate isolation with good performance
Use cloud providers (E2B, Modal) for maximum security and isolation
Match compute choice to your specific use case (Modal for ML, Flyio for edge)

Model Selection with Litellm

Use litellm prefixes correctly for different providers:

Always include provider prefix for Gemini: gemini/gemini-2.0-flash
Always include provider prefix for Ollama: ollama/llama3
OpenAI models can omit prefix: gpt-4o or openai/gpt-4o
Test model availability before production deployment

Preferred LocalAgent Usage

Use the new canonical LocalAgent class instead of the deprecated factory:

Avoid the provider= parameter entirely on LocalAgent constructors
Use config.model= to specify LLM models with appropriate litellm prefixes
Use compute= to specify sandboxing backends separately from LLM choice
This provides cleaner separation of concerns and better maintainability

Environment Variables

Properly configure API keys and credentials:

Set LLM provider keys (OPENAI_API_KEY, GOOGLE_API_KEY, etc.)
Set compute provider keys (E2B_API_KEY, MODAL_TOKEN, etc.)
Use environment variable management tools for production deployments
Test authentication before deploying to avoid runtime failures

Where Does It Run

Ask any agent where its thinking and tools actually execute

Hosted Agent

Run entire agent loops on Anthropic’s managed runtime

Sandbox

Tool execution sandboxing options

ManagedAgent Persistence

Database integration patterns

Session Info

Session metadata and usage tracking

​Quick Start

​How It Works

​Choosing an LLM

​Choosing a Compute Backend

​Compute Selection Guide

​File-based defaults

​Configuration Options

LocalAgent API Reference

LocalAgentConfig Reference

​Common Patterns

​Switching LLMs

​Tool Execution

​Multi-turn Conversations

​Usage Tracking

​Multi-tenant safety

​Migrating from ManagedAgent

​Best Practices

​Related

Where Does It Run

Hosted Agent

Sandbox

ManagedAgent Persistence

Session Info

Quick Start

How It Works

Choosing an LLM

Choosing a Compute Backend

Compute Selection Guide

File-based defaults

Configuration Options

Common Patterns

Switching LLMs

Tool Execution

Multi-turn Conversations

Usage Tracking

Multi-tenant safety

Migrating from ManagedAgent

Best Practices

Related