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

# HostedAgent + Database Persistence

> Run agents on Anthropic's infrastructure while persisting session data to your database

<Note>
  `ManagedAgent` is deprecated as of PR #1550. New code should use `HostedAgent` for Anthropic-hosted runs (this page) or `LocalAgent` for local loops. Existing imports continue to work but emit a `DeprecationWarning` for non-Anthropic providers.
</Note>

HostedAgent executes on Anthropic's managed infrastructure while seamlessly persisting conversation history and session state to your choice of 7 database backends.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "HostedAgent + Database Persistence"
        A[📝 User Input] --> B[🧠 Anthropic Infrastructure]
        B --> C[💾 Your Database]
        C --> D[✅ Session Resume]
    end
    
    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef storage fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff
    
    class A input
    class B process
    class C storage
    class D output
```

## Quick Start

<Steps>
  <Step title="Basic Usage">
    Run `gpt-4o-mini` conversations with SQLite persistence in 5 lines:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, db
    from praisonai import HostedAgent, HostedAgentConfig

    hosted = HostedAgent(
        provider="anthropic",
        config=HostedAgentConfig(model="gpt-4o-mini", system="You are helpful")
    )

    agent = Agent(
        name="Assistant", 
        backend=hosted,
        db=db(database_url="conversation.db"),
        session_id="session-1"
    )

    agent.start("Remember: The sky is blue")
    ```
  </Step>

  <Step title="Session Resume">
    Continue conversations after restarts:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Later process - same session_id resumes conversation
    agent2 = Agent(
        name="Assistant",
        backend=hosted,
        db=db(database_url="conversation.db"), 
        session_id="session-1"  # Same ID = resume
    )

    response = agent2.start("What color is the sky?")
    # Response: "The sky is blue" (remembers from previous session)
    ```
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant HostedAgent
    participant Anthropic
    participant Database
    
    User->>HostedAgent: "Remember: X"
    HostedAgent->>Anthropic: Create session & execute
    Anthropic-->>HostedAgent: Response + usage
    HostedAgent->>Database: Store messages & metadata
    Database-->>User: Session persisted
    
    Note over User,Database: Instance destroyed
    
    User->>HostedAgent: Resume session
    HostedAgent->>Database: Load chat history
    Database-->>HostedAgent: Previous messages
    HostedAgent->>Anthropic: Continue session
    Anthropic-->>HostedAgent: Context-aware response
    ManagedAgent-->>User: "I remember X"
```

***

## Database Backends

<Tabs>
  <Tab title="SQLite">
    Zero external dependencies, file-based storage:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, db
    from praisonai import HostedAgent, HostedAgentConfig

    # Phase 1: First session (teach facts)
    hosted = HostedAgent(
        provider="anthropic",
        config=HostedAgentConfig(model="gpt-4o-mini", system="You are helpful")
    )

    agent = Agent(
        name="Assistant",
        backend=hosted,
        db=db(database_url="sqlite:///my_data.db"),
        session_id="learning-session"
    )

    agent.start("Remember: PraisonAI is an AI agent framework")
    agent.start("Also remember: It supports multiple LLM providers")

    # Phase 2: Direct verification
    import sqlite3
    conn = sqlite3.connect("my_data.db")
    cursor = conn.cursor()
    cursor.execute("SELECT COUNT(*) FROM messages WHERE session_id = ?", ("learning-session",))
    message_count = cursor.fetchone()[0]
    print(f"Messages stored: {message_count}")
    conn.close()

    # Phase 3: Session resume (new instance)
    hosted2 = HostedAgent(
        provider="anthropic", 
        config=HostedAgentConfig(model="gpt-4o-mini", system="You are helpful")
    )

    agent2 = Agent(
        name="Assistant",
        backend=hosted2,
        db=db(database_url="sqlite:///my_data.db"),
        session_id="learning-session"  # Same ID resumes
    )

    result = agent2.start("What did I tell you about PraisonAI?")
    # Result: "You told me that PraisonAI is an AI agent framework and that it supports multiple LLM providers."
    ```

    **Prerequisites:** None (built into Python)
  </Tab>

  <Tab title="PostgreSQL">
    Production-ready relational database:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, db
    from praisonai import HostedAgent, HostedAgentConfig
    import psycopg2

    # Phase 1: First session
    hosted = HostedAgent(
        provider="anthropic",
        config=HostedAgentConfig(model="gpt-4o-mini", system="You are an expert assistant")
    )

    agent = Agent(
        name="Expert",
        backend=hosted,
        db=db(database_url="postgresql://user:pass@localhost:5432/praisondb"),
        session_id="expert-session"
    )

    agent.start("Remember: PostgreSQL is ACID compliant")
    agent.start("Remember: It supports JSON columns")

    # Phase 2: Direct verification
    conn = psycopg2.connect("postgresql://user:pass@localhost:5432/praisondb")
    cursor = conn.cursor()
    cursor.execute("SELECT content FROM messages WHERE session_id = %s", ("expert-session",))
    messages = cursor.fetchall()
    print(f"Stored {len(messages)} messages")
    conn.close()

    # Phase 3: Resume session
    hosted2 = HostedAgent(
        provider="anthropic",
        config=HostedAgentConfig(model="gpt-4o-mini", system="You are an expert assistant")
    )

    agent2 = Agent(
        name="Expert",
        backend=hosted2, 
        db=db(database_url="postgresql://user:pass@localhost:5432/praisondb"),
        session_id="expert-session"
    )

    result = agent2.start("What database features did I mention?")
    # Result: "You mentioned that PostgreSQL is ACID compliant and supports JSON columns."
    ```

    **Prerequisites:**

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install psycopg2-binary
    # Docker: docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=pass postgres
    ```
  </Tab>

  <Tab title="MySQL">
    Popular relational database:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, db
    from praisonai import HostedAgent, HostedAgentConfig
    import mysql.connector

    hosted = HostedAgent(
        provider="anthropic",
        config=HostedAgentConfig(model="gpt-4o-mini", system="You are helpful")
    )

    agent = Agent(
        name="Assistant",
        backend=hosted,
        db=db(database_url="mysql://user:pass@localhost:3306/praisondb"),
        session_id="mysql-session" 
    )

    agent.start("Remember: MySQL is owned by Oracle")

    # Direct verification
    conn = mysql.connector.connect(
        host="localhost", user="user", password="pass", database="praisondb"
    )
    cursor = conn.cursor()
    cursor.execute("SELECT COUNT(*) FROM messages WHERE session_id = %s", ("mysql-session",))
    count = cursor.fetchone()[0]
    print(f"Messages: {count}")
    conn.close()

    # Resume later
    agent2 = Agent(
        name="Assistant",
        backend=hosted,
        db=db(database_url="mysql://user:pass@localhost:3306/praisondb"),
        session_id="mysql-session"
    )

    result = agent2.start("Who owns MySQL?")
    # Result: "MySQL is owned by Oracle."
    ```

    **Prerequisites:**

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install mysql-connector-python
    # Docker: docker run -d -p 3306:3306 -e MYSQL_ROOT_PASSWORD=pass mysql
    ```
  </Tab>

  <Tab title="Redis">
    State storage with conversation store:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, db
    from praisonai import HostedAgent, HostedAgentConfig
    import redis

    hosted = HostedAgent(
        provider="anthropic",
        config=HostedAgentConfig(model="gpt-4o-mini", system="You are helpful")
    )

    # Redis for state + SQLite for conversations
    agent = Agent(
        name="Assistant",
        backend=hosted,
        db=db(
            database_url="sqlite:///conversations.db",  # Conversation store
            state_url="redis://localhost:6379"         # State store
        ),
        session_id="redis-session"
    )

    agent.start("Remember: Redis is in-memory")

    # Direct verification  
    r = redis.Redis(host="localhost", port=6379, decode_responses=True)
    state_keys = r.keys("*redis-session*")
    print(f"State keys: {len(state_keys)}")

    # Resume session
    agent2 = Agent(
        name="Assistant", 
        backend=hosted,
        db=db(
            database_url="sqlite:///conversations.db",
            state_url="redis://localhost:6379"
        ),
        session_id="redis-session"
    )

    result = agent2.start("What type of database is Redis?")
    # Result: "Redis is an in-memory database."
    ```

    **Prerequisites:**

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install redis
    # Docker: docker run -d -p 6379:6379 redis
    ```
  </Tab>

  <Tab title="MongoDB">
    Document database for state:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, db
    from praisonai import HostedAgent, HostedAgentConfig
    import pymongo

    hosted = HostedAgent(
        provider="anthropic",
        config=HostedAgentConfig(model="gpt-4o-mini", system="You are helpful")
    )

    # MongoDB for state + SQLite for conversations
    agent = Agent(
        name="Assistant",
        backend=hosted,
        db=db(
            database_url="sqlite:///conversations.db",      # Conversation store
            state_url="mongodb://localhost:27017/praisondb" # State store  
        ),
        session_id="mongo-session"
    )

    agent.start("Remember: MongoDB stores documents")

    # Direct verification
    client = pymongo.MongoClient("mongodb://localhost:27017/")
    db_mongo = client["praisondb"]
    state_count = db_mongo.state.count_documents({"session_id": "mongo-session"})
    print(f"State documents: {state_count}")

    # Resume session  
    agent2 = Agent(
        name="Assistant",
        backend=hosted,
        db=db(
            database_url="sqlite:///conversations.db",
            state_url="mongodb://localhost:27017/praisondb"
        ),
        session_id="mongo-session"
    )

    result = agent2.start("What does MongoDB store?")
    # Result: "MongoDB stores documents."
    ```

    **Prerequisites:**

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install pymongo
    # Docker: docker run -d -p 27017:27017 mongo
    ```
  </Tab>

  <Tab title="ClickHouse">
    Analytics database with conversation store:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, db
    from praisonai import HostedAgent, HostedAgentConfig
    import clickhouse_connect

    hosted = HostedAgent(
        provider="anthropic",
        config=HostedAgentConfig(model="gpt-4o-mini", system="You are helpful")  
    )

    # ClickHouse for analytics + SQLite for conversations
    agent = Agent(
        name="Assistant",
        backend=hosted,
        db=db(
            database_url="sqlite:///conversations.db",           # Conversation store
            analytics_url="clickhouse://localhost:8123/default"  # Analytics store
        ),
        session_id="clickhouse-session"
    )

    agent.start("Remember: ClickHouse is columnar")

    # Direct verification
    client = clickhouse_connect.get_client(host="localhost", port=8123)
    result = client.query("SELECT count() FROM analytics WHERE session_id = 'clickhouse-session'")
    print(f"Analytics rows: {result.result_rows[0][0]}")

    # Resume session
    agent2 = Agent(
        name="Assistant",
        backend=hosted,
        db=db(
            database_url="sqlite:///conversations.db",
            analytics_url="clickhouse://localhost:8123/default"
        ),
        session_id="clickhouse-session"
    )

    result = agent2.start("What type of database is ClickHouse?")
    # Result: "ClickHouse is a columnar database."
    ```

    **Prerequisites:**

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install clickhouse-connect
    # Docker: docker run -d -p 8123:8123 clickhouse/clickhouse-server
    ```
  </Tab>

  <Tab title="JSON Files">
    Zero dependencies with built-in session store:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent
    from praisonai import HostedAgent, HostedAgentConfig
    from praisonaiagents.session.store import DefaultSessionStore
    import json
    import os

    hosted = HostedAgent(
        provider="anthropic", 
        config=HostedAgentConfig(model="gpt-4o-mini", system="You are helpful")
    )

    # JSON file-based session store (no external deps)
    store = DefaultSessionStore(directory="./sessions")

    agent = Agent(
        name="Assistant",
        backend=hosted,
        session_store=store,
        session_id="json-session"
    )

    agent.start("Remember: JSON is human-readable")

    # Direct verification
    session_file = "./sessions/json-session.json"
    if os.path.exists(session_file):
        with open(session_file, 'r') as f:
            data = json.load(f)
            print(f"Messages stored: {len(data.get('messages', []))}")

    # Resume session
    agent2 = Agent(
        name="Assistant",
        backend=hosted,
        session_store=DefaultSessionStore(directory="./sessions"),
        session_id="json-session"
    )

    result = agent2.start("What format is JSON?")
    # Result: "JSON is human-readable."
    ```

    **Prerequisites:** None (built into Python)
  </Tab>
</Tabs>

***

## Configuration Options

<Card title="HostedAgent API Reference" icon="code" href="/docs/sdk/reference/typescript/classes/HostedAgent">
  Complete HostedAgent configuration options
</Card>

<Card title="PraisonDB Reference" icon="database" href="/docs/sdk/reference/typescript/classes/PraisonDB">
  Database adapter configuration options
</Card>

| Component           | Purpose                     | Key Parameters                               |
| ------------------- | --------------------------- | -------------------------------------------- |
| `HostedAgent`       | Anthropic execution backend | `provider`, `config`, `api_key`, `timeout`   |
| `HostedAgentConfig` | Agent definition            | `model`, `system`, `tools`, `packages`       |
| `PraisonDB`         | Database adapter            | `database_url`, `state_url`, `analytics_url` |
| `DbSessionAdapter`  | Session bridge              | Auto-configured based on database URL        |

***

## Common Patterns

<AccordionGroup>
  <Accordion title="Session Resume Pattern">
    The most common pattern for persistent managed agents:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, db
    from praisonai import HostedAgent, HostedAgentConfig

    def create_agent(session_id: str):
        hosted = HostedAgent(
            provider="anthropic",
            config=HostedAgentConfig(
                model="gpt-4o-mini",
                system="You are a helpful assistant with perfect memory"
            )
        )
        
        return Agent(
            name="PersistentAgent",
            backend=hosted,
            db=db(database_url="postgresql://localhost/agentdb"),
            session_id=session_id
        )

    # First conversation
    agent1 = create_agent("user-123")
    agent1.start("My name is Alice and I live in Paris")

    # Later conversation (different process/server restart)
    agent2 = create_agent("user-123")  # Same session_id
    response = agent2.start("What's my name and where do I live?")
    # Response: "Your name is Alice and you live in Paris."
    ```
  </Accordion>

  <Accordion title="Multi-Backend Pattern">
    Use different backends for different data types:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, db
    from praisonai import HostedAgent, HostedAgentConfig

    hosted = HostedAgent(
        provider="anthropic",
        config=HostedAgentConfig(model="gpt-4o-mini")
    )

    agent = Agent(
        name="MultiBackendAgent",
        backend=hosted,
        db=db(
            database_url="postgresql://localhost/conversations",  # Conversations
            state_url="redis://localhost:6379",                  # Fast state
            analytics_url="clickhouse://localhost:8123/default"  # Analytics
        ),
        session_id="multi-backend-session"
    )

    # All data types are automatically stored in appropriate backends
    agent.start("Analyze this data and remember the insights")
    ```
  </Accordion>

  <Accordion title="Session ID Management">
    Best practices for session identification:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, db
    from praisonai import HostedAgent, HostedAgentConfig
    import hashlib
    from datetime import datetime

    def generate_session_id(user_id: str, conversation_type: str) -> str:
        """Generate deterministic session IDs"""
        # Per-user, per-type sessions
        base = f"{user_id}-{conversation_type}"
        return hashlib.md5(base.encode()).hexdigest()[:16]

    def get_daily_session_id(user_id: str) -> str:
        """Daily session rotation"""
        today = datetime.now().strftime("%Y-%m-%d")
        return f"{user_id}-{today}"

    # Usage examples
    user_session = generate_session_id("user-456", "support")
    daily_session = get_daily_session_id("user-456")

    hosted = HostedAgent(
        provider="anthropic",
        config=HostedAgentConfig(model="gpt-4o-mini")
    )

    agent = Agent(
        name="SupportAgent",
        backend=hosted,
        db=db(database_url="sqlite:///support.db"),
        session_id=user_session  # Consistent across requests
    )
    ```
  </Accordion>
</AccordionGroup>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Session Management">
    * Use meaningful session IDs (user-based, not random)
    * Implement session rotation for long conversations
    * Store session metadata for debugging
    * Handle concurrent access with proper locking
  </Accordion>

  <Accordion title="Database Selection">
    * **SQLite**: Development, single-user apps, file-based persistence
    * **PostgreSQL**: Production apps, complex queries, ACID compliance
    * **MySQL**: Existing MySQL infrastructure, compatibility requirements
    * **Redis**: High-speed state, session caching, temporary data
    * **MongoDB**: Document-based state, flexible schemas
    * **ClickHouse**: Analytics, large-scale logging, data warehousing
    * **JSON Files**: Prototyping, zero dependencies, simple use cases
  </Accordion>

  <Accordion title="Performance Optimization">
    * Use connection pooling for database connections
    * Implement message compaction for long sessions
    * Cache frequently accessed session data
    * Use async database operations when possible
    * Monitor database performance metrics
  </Accordion>

  <Accordion title="Error Handling">
    * Implement retry logic for transient database failures
    * Handle session corruption gracefully
    * Log database errors for debugging
    * Provide fallback behavior when persistence fails
    * Test database connection before agent creation
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Hosted Agent" icon="cloud" href="/docs/features/hosted-agent">
    Run entire agent loops on Anthropic's managed runtime
  </Card>

  <Card title="Local Agent" icon="desktop" href="/docs/features/local-agent">
    Run agent loops locally with any LLM
  </Card>

  <Card title="Managed CLI" icon="terminal" href="/docs/features/managed-cli">
    Terminal commands for managing Anthropic-hosted resources
  </Card>

  <Card title="Session Management" icon="clock" href="/docs/features/sessions">
    Advanced session handling techniques
  </Card>
</CardGroup>