Skip to main content
HostedAgent runs the complete agent execution loop on Anthropic’s managed infrastructure, providing seamless cloud-based agent processing with built-in tools and session management. 
from praisonaiagents import Agent
from praisonai import HostedAgent, HostedAgentConfig

agent = Agent(name="assistant", instructions="Be helpful.")

hosted = HostedAgent(
    provider="anthropic",
    config=HostedAgentConfig(model="claude-sonnet-4-20250514"),
)

hosted.start("Summarise this document")
The user sends a request; the full agent loop runs on Anthropic’s hosted runtime.

​
Quick Start

1

Simple Usage

Create a hosted agent with minimal configuration:
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")
2

With Tools and Multi-Turn

Enable agent tools and demonstrate session continuity:
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

ComponentLocationPurpose
Agent LoopAnthropic CloudComplete execution environment
ToolsAnthropic CloudSandboxed tool execution
LLMAnthropic CloudClaude model processing
Session StateAnthropic CloudPersistent conversation context

​
When to Use HostedAgent vs LocalAgent

​
Configuration Options

HostedAgent API Reference

Complete HostedAgent configuration options

HostedAgentConfig Reference

Configuration object parameters
OptionTypeDefaultDescription
modelstr"claude-haiku-4-5"Claude model to use
systemstr"You are a helpful coding assistant."System prompt
namestr"Agent"Agent display name
toolsList[Dict][{"type": "agent_toolset_20260401"}]Available tools
packagesDictNonePackage dependencies
networkingDictUnrestrictedNetwork configuration

​
Common Patterns

​
Multi-turn Conversation

Anthropic maintains session state in the cloud between calls: 
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: 
# 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: 
# 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.

​
Entry-point registration

A pip-installable package can publish a new HostedAgent provider by declaring an entry point: 
# 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: 
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

Register a backend without an entry point for testing or embedding: 
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: 
# 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

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

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