> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Hosted Agent Flow"
A[📝 User Request] --> B[🌐 HostedAgent]
B --> C[☁️ Anthropic Cloud]
C --> D[🔧 Cloud Tools]
D --> E[✅ Response]
end
classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
classDef cloud fill:#10B981,stroke:#7C90A0,color:#fff
classDef tools fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef output fill:#6366F1,stroke:#7C90A0,color:#fff
class A input
class B process
class C cloud
class D tools
class E output
```
## Quick Start
Create a hosted agent with minimal configuration:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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")
```
Enable agent tools and demonstrate session continuity:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant HostedAgent
participant Anthropic
User->>Agent: Request
Agent->>HostedAgent: Execute
HostedAgent->>Anthropic: Create session & run loop
Note over Anthropic: Complete agent loop runs in cloud
Note over Anthropic: Tools execute in managed environment
Note over Anthropic: LLM processing & context management
Anthropic-->>HostedAgent: Stream response
HostedAgent-->>Agent: Return result
Agent-->>User: Response
```
| 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
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
A[Choose Agent Backend] --> B{Where should execution happen?}
B -->|Cloud Infrastructure| C[HostedAgent]
B -->|Local Process| D[LocalAgent]
C --> E[✅ Fully managed runtime]
C --> F[✅ Built-in tool sandboxing]
C --> G[✅ Anthropic infrastructure]
D --> H[✅ Any LLM provider]
D --> I[✅ Local execution control]
D --> J[✅ Custom compute backends]
classDef hosted fill:#10B981,stroke:#7C90A0,color:#fff
classDef local fill:#189AB4,stroke:#7C90A0,color:#fff
classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
class C,E,F,G hosted
class D,H,I,J local
class A,B decision
```
***
## Configuration Options
Complete HostedAgent configuration options
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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")
```
***
## Migrating from ManagedAgent
Replace the deprecated `ManagedAgent` factory with the new canonical class:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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
***
## Related
Run agent loops locally with any LLM
Database integration with hosted agents
Session metadata and usage tracking
Command-line tools for hosted resources