Local Agent

Run the agent loop locally with any LLM and optional cloud-sandboxed tools

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

python

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.

Diagram

Quick Start

Simplest Usage

Create a local agent with minimal configuration:

python

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:

python

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")

How It Works

Diagram

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

Use OpenAI models with API key authentication:

python

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"
    )
)

Gemini

Use Google’s Gemini models:

python

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
    )
)

Ollama

Use local Ollama models:

python

from praisonai import LocalAgent, LocalAgentConfig

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

Anthropic

Use Claude models via API:

python

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"
    )
)

Custom

Use any litellm-supported provider:

python

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

None (Local)

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

python

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"]
    )
)

Warning

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:

text

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

Rewrite options as plain specifiers:

python

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

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

Docker

Execute tools in Docker containers:

python

from praisonai import LocalAgent, LocalAgentConfig

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

E2B

Execute tools in E2B cloud sandboxes:

python

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"]
    )
)

Modal

Execute tools on Modal cloud compute:

python

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"]
    )
)

Flyio

Execute tools on Fly.io infrastructure:

python

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"]
    )
)

Daytona

Execute tools in Daytona development environments:

python

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"]
    )
)

Novita

Execute tools in Novita cloud sandboxes:

python

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

Diagram

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.

Card

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

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:

python

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:

python

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:

python

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:

python

# 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.

python

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)

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

Local Agent

Quick Start

How It Works

Choosing an LLM

OpenAI

Gemini

Ollama

Anthropic

Custom

Choosing a Compute Backend

None (Local)

Docker

E2B

Modal

Flyio

Daytona

Novita

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