Hosted Agent

Host the whole agent loop away from your process — on Anthropic, or in any registered compute runtime

HostedAgent hosts the whole agent loop away from your process — on Anthropic, or in any registered compute runtime (Docker, E2B, Modal, Daytona, Fly.io, Tenki).

python

from praisonaiagents import Agent
from praisonai import HostedAgent, HostedAgentConfig

# Anthropic-hosted loop (the classic case)
agent = Agent(backend=HostedAgent(provider="anthropic"))

# Same class, Daytona-hosted loop (guaranteed since PR #4074)
agent = Agent(backend=HostedAgent(
    provider="daytona",
    config=HostedAgentConfig(model="gpt-4o-mini"),
))

The user sends a request; the full agent loop runs on the chosen provider’s hosted runtime.

Diagram

Quick Start

Simple Usage

Create a hosted agent with minimal configuration:

python

from praisonai import HostedAgent, HostedAgentConfig
from praisonaiagents import Agent

hosted = HostedAgent(
    provider="anthropic",
    config=HostedAgentConfig(
        model="claude-3-5-sonnet-latest",
        system="You are a helpful coding assistant."
    )
)

agent = Agent(name="coder", backend=hosted)
result = agent.start("Create a simple Python function to calculate fibonacci numbers")

With Tools and Multi-Turn

Enable agent tools and demonstrate session continuity:

python

from praisonai import HostedAgent, HostedAgentConfig
from praisonaiagents import Agent

hosted = HostedAgent(
    provider="anthropic",
    config=HostedAgentConfig(
        model="claude-3-5-sonnet-latest",
        system="You are a helpful assistant with access to tools.",
        tools=[{"type": "agent_toolset_20260401"}]
    )
)

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

# First turn
result1 = agent.start("Write a Python script to list files in current directory")

# Second turn - continues same session
result2 = agent.start("Now modify it to only show Python files")

How It Works

Diagram

Component	Location	Purpose
Agent Loop	Anthropic Cloud	Complete execution environment
Tools	Anthropic Cloud	Sandboxed tool execution
LLM	Anthropic Cloud	Claude model processing
Session State	Anthropic Cloud	Persistent conversation context

When to Use HostedAgent vs LocalAgent

Diagram

Which provider should I pick?

anthropic is one entry in the backend registry; every registered compute runtime is another.

Diagram

Which providers resolve vs raise

Registered compute runtimes resolve; LLM routing names raise a ValueError that points at LocalAgent.

`provider=` value	Resolves	Raises `ValueError`
`anthropic`	✅
`docker`, `e2b`, `modal`, `daytona`, `flyio`, `tenki`	✅
`openai`, `gemini`, `ollama`, `local`		✅ (“use `LocalAgent`“)
anything unregistered		✅

For openai, gemini, ollama, and local, use LocalAgent instead:

python

from praisonai import LocalAgent, LocalAgentConfig

agent = LocalAgent(config=LocalAgentConfig(model="openai/gpt-4o"))

Configuration Options

HostedAgent API Reference

Complete HostedAgent configuration options

HostedAgentConfig Reference

Configuration object parameters

Option	Type	Default	Description
`model`	`str`	`"claude-haiku-4-5"`	Claude model to use
`system`	`str`	`"You are a helpful coding assistant."`	System prompt
`name`	`str`	`"Agent"`	Agent display name
`tools`	`List[Dict]`	`[{"type": "agent_toolset_20260401"}]`	Available tools
`packages`	`Dict`	`None`	Package dependencies
`networking`	`Dict`	Unrestricted	Network configuration

Common Patterns

Multi-turn Conversation

Anthropic maintains session state in the cloud between calls:

python

from praisonai import HostedAgent, HostedAgentConfig
from praisonaiagents import Agent

hosted = HostedAgent(
    provider="anthropic",
    config=HostedAgentConfig(
        model="claude-3-5-sonnet-latest",
        system="You are a helpful assistant with perfect memory."
    )
)

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

# First conversation
agent.start("My favorite color is blue")

# Later conversation - agent remembers
response = agent.start("What's my favorite color?")
# Response: "Your favorite color is blue."

Usage Tracking

Retrieve session information and usage metrics:

python

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

# List all sessions for this agent
sessions = hosted.list_sessions()
for session in sessions:
    print(f"Session {session['id']}: {session['status']}")

Session Management

List and manage active sessions:

python

# List all sessions
sessions = hosted.list_sessions()

# Archive a specific session
hosted.archive_session("sesn_123...")

# Resume a previous session by ID
hosted.resume_session("sesn_123...")
agent.start("Continue where we left off")

Pluggable Provider Backends

HostedAgent uses ManagedBackendRegistry to look up provider backends — third-party packages can register new providers via the praisonai.managed_backends entry-point group.

docker is now a built-in provider alongside anthropic, resolved through the same registry (no plugin needed). HostedAgent(provider="docker") runs the whole agent in a local container — see Self-Hosted Agent (Docker).

Diagram

Entry-point registration

A pip-installable package can publish a new HostedAgent provider by declaring an entry point:

toml

# pyproject.toml
[project.entry-points."praisonai.managed_backends"]
e2b = "e2b_praisonai.backend:E2BManagedAgent"

After pip install e2b-praisonai, HostedAgent(provider="e2b") resolves it automatically — no core change needed.

Factory semantics

For non-Anthropic backends, HostedAgent.__new__ acts as a factory — it returns the resolved backend instance directly. Python skips __init__ when __new__ returns a non-cls instance, so callers get the real backend’s methods rather than Anthropic-inherited ones:

python

from praisonai import HostedAgent, HostedAgentConfig
from praisonaiagents import Agent

# A third-party "e2b" plugin is installed via pip.
# HostedAgent resolves it through the registry — no core change.
hosted = HostedAgent(
    provider="e2b",
    config=HostedAgentConfig(model="claude-haiku-4-5"),
)

agent = Agent(name="Researcher", instructions="Research and summarise.", llm=hosted)
agent.start("Find three sources on agentic RAG.")

Programmatic registration

python

from praisonai import HostedAgent, HostedAgentConfig
from praisonaiagents import Agent

class E2BManagedAgent:
    def __init__(self, provider, config=None, **kwargs):
        self.provider = provider
        self.config = config

    def is_available(self):
        try:
            import e2b
            return True
        except ImportError:
            return False

from praisonai.integrations.backend_registry import get_backend_registry
get_backend_registry().register("e2b", E2BManagedAgent)

hosted = HostedAgent(provider="e2b", config=HostedAgentConfig(model="claude-haiku-4-5"))
agent = Agent(name="Coder", instructions="Write code.", llm=hosted)
agent.start("Write a hello world script.")

Error message

When HostedAgent(provider="unknown") is called with an unregistered provider, the error lists available backends:

ValueError: Managed runtime for provider 'unknown' is not available.
Available: ['anthropic', 'e2b', ...]

Cross-reference: Managed Backend Plugins — full guide to authoring and publishing provider backends.

Migrating from ManagedAgent

Replace the deprecated ManagedAgent factory with the new canonical class:

python

# Before (deprecated)
from praisonai.integrations.managed_agents import ManagedAgent, ManagedConfig

managed = ManagedAgent(
    provider="anthropic",
    config=ManagedConfig(
        model="claude-3-5-sonnet-latest",
        system="You are helpful"
    )
)

# After (canonical)
from praisonai import HostedAgent, HostedAgentConfig

hosted = HostedAgent(
    provider="anthropic",
    config=HostedAgentConfig(
        model="claude-3-5-sonnet-latest",
        system="You are helpful"
    )
)

Best Practices

Managing API Costs

Use claude-haiku-4-5 for simple tasks to minimize costs
Implement usage tracking with retrieve_session() to monitor token consumption
Set appropriate tool policies to control execution overhead
Archive old sessions to avoid accumulating state storage costs

Choosing Tools

Use agent_toolset_20260401 for general-purpose tool access
Specify minimal tool sets to reduce complexity and cost
Test tool combinations in development before production deployment
Review tool execution logs via session metadata

Session Reuse

Reuse sessions for related conversations to maintain context
Implement session ID management for user-specific contexts
Use resume_session() to continue conversations across application restarts
Archive sessions when conversations are complete

Error Handling

Handle ValueError for unsupported providers gracefully
Implement retry logic for transient network issues
Use interrupt() to stop long-running operations
Monitor session status and handle error states appropriately

HostedAgent Compute Runtimes

Run the whole loop in Docker, E2B, Modal, Daytona, Fly.io, or Tenki

Placement — where does my agent run?

Agent(run_on="daytona") is the short form of this factory

Self-Hosted Agent (Docker)

run_on="docker" — the whole agent in a container you own

Where Does It Run

Ask any agent where its thinking and tools actually execute

Local Agent

Run agent loops locally with any LLM

Managed Backend Plugins

Add new HostedAgent providers via entry points

ManagedAgent Persistence

Database integration with hosted agents

Session Info

Session metadata and usage tracking

Hosted Agent

Quick Start

How It Works

When to Use HostedAgent vs LocalAgent

Which provider should I pick?

Which providers resolve vs raise

Configuration Options

Common Patterns

Multi-turn Conversation

Usage Tracking

Session Management

Pluggable Provider Backends

Entry-point registration

Factory semantics

Programmatic registration

Error message

Migrating from ManagedAgent

Best Practices

Related