Hosted Agent

Run the entire agent loop on Anthropic’s managed cloud runtime

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

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

---

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:

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

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

---

Related

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