Session Management

Agents support multi-turn conversations with automatic session management.

How It Works

1. First message — Send a prompt without conversationId. The platform creates a new conversation and returns a conversationId in the __META__ response.
2. Follow-up messages — Include the conversationId to continue the conversation. The agent sees the full history.
3. Storage — Conversation history is stored in S3 via Strands S3SessionManager. Each conversation gets its own S3 prefix.

Starting a Conversation

curl -s -X POST https://stream.api.universalapi.co/agent/AGENT_ID/chat \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is machine learning?"}'

Response includes:

Machine learning is a subset of artificial intelligence...

__META__{"conversationId":"conv-abc123","agentId":"agent-xxx","bedrockProvider":"platform"}

Continuing a Conversation

curl -s -X POST https://stream.api.universalapi.co/agent/AGENT_ID/chat \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Can you give me a specific example?",
    "conversationId": "conv-abc123"
  }'

The agent remembers the previous context and responds accordingly.

Listing Conversations

curl -s https://api.universalapi.co/agent/AGENT_ID/conversations \
  -H "Authorization: Bearer YOUR_TOKEN" | jq

{
  "data": {
    "conversations": [
      {
        "conversationId": "conv-abc123",
        "title": "Machine Learning Discussion",
        "messageCount": 4,
        "createdAt": "2026-03-05T20:00:00Z",
        "updatedAt": "2026-03-05T20:05:00Z"
      }
    ]
  }
}

Getting Conversation History

curl -s https://api.universalapi.co/agent/AGENT_ID/conversations/conv-abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" | jq

{
  "data": {
    "conversationId": "conv-abc123",
    "messages": [
      {"role": "user", "content": "What is machine learning?"},
      {"role": "assistant", "content": "Machine learning is a subset of..."},
      {"role": "user", "content": "Can you give me a specific example?"},
      {"role": "assistant", "content": "Sure! A common example is..."}
    ]
  }
}

Session Limits

• Conversation history is limited by the model's context window (typically 200K tokens for Claude)
• No expiration — conversations persist indefinitely in S3
• Per-user isolation — users can only access their own conversations
• Cost — each message in a conversation includes the full history, so longer conversations use more tokens (and credits)

For Agent Authors

CRITICAL — You must pass session_manager to your Agent

The platform pre-injects a session_manager variable into your agent's execution scope. You must pass it to the Agent() constructor for multi-turn conversations to work.

def create_agent():
    model = BedrockModel(
        model_id="us.anthropic.claude-sonnet-4-20250514-v1:0",
        region_name="us-east-1"
    )
    agent = Agent(
        model=model,
        system_prompt="You are a helpful assistant.",
        session_manager=session_manager  # ← Pre-injected by the UAPI runtime
    )
    return agent, []

What the platform handles automatically:

• Creating S3SessionManager instances (stored in S3, scoped per-user per-agent)
• Loading conversation history when conversationId is provided
• Saving updated history after each response
• Generating unique conversationId values for new conversations

What you must do:

• Pass session_manager=session_manager in your Agent() constructor

Without this, each message starts a fresh conversation with no memory of previous turns — the agent won't remember anything the user said before.

See Creating Agents → Session Management for more details.