API Documentation

API Documentation

Quick Start

The agent runs on http://localhost:8000 by default. All endpoints return JSON except /agent/stream which uses Server-Sent Events.

Endpoints

Health Check

GET /health

Returns service status. Useful for load balancer health checks.

curl http://localhost:8000/health

Response:

{
  "status": "healthy",
  "service": "consumer-agent-python",
  "version": "0.1.0"
}

Stream Chat Response

POST /agent/stream

Main endpoint for chat interactions. Streams responses in real-time using SSE.

Basic request:

curl -X POST http://localhost:8000/agent/stream \
  -H "Content-Type: application/json" \
  -H "userId: user123" \
  -d '{
    "messages": [{"role": "user", "content": "Hello!"}],
    "agent_id": "conversational",
    "enabled_components": []
  }'

With location context:

curl -X POST http://localhost:8000/agent/stream \
  -H "Content-Type: application/json" \
  -H "userId: user123" \
  -d '{
    "messages": [{"role": "user", "content": "Find pizza offers near me"}],
    "agent_id": "conversational",
    "latitude": 41.8781,
    "longitude": -87.6298,
    "enabled_components": ["offer-list"]
  }'

Multi-turn conversation:

curl -X POST http://localhost:8000/agent/stream \
  -H "Content-Type: application/json" \
  -H "userId: user123" \
  -d '{
    "messages": [
      {"role": "user", "content": "Find pizza offers"},
      {"role": "assistant", "content": "Found 5 offers nearby"},
      {"role": "user", "content": "What are the cheapest?"}
    ],
    "agent_id": "conversational",
    "enabled_components": ["offer-list"]
  }'

Request Format

Required fields:

• messages - Array of message objects with role and content
• enabled_components - Array of component names (can be empty [])
• agent_id - Agent to use: “conversational” (with tools) or “prompt-suggestions” (no tools)

Optional fields:

• latitude / longitude - For location-based queries (defaults to 0.0)
• locale - Language preference (“en” or “es-419”)

Headers:

• userId - User identifier (recommended for personalization)
• Accept-Language - Browser language preference
• Content-Type: application/json - Required

Response Format

Responses are streamed as Server-Sent Events. Each event is formatted as:

data: {"type": "text", "content": "Hello"}

data: [DONE]

Event types:

• text - Regular response text
• reasoning - Internal thinking (extended thinking models)
• tool_call_start - Tool execution beginning
• tool_call_end - Tool execution complete with duration
• completed - Stream finished
• error - Something went wrong

Example events:

{"type": "text", "content": "I found several pizza offers"}
{"type": "tool_call_start", "tool_id": "call_abc", "tool_name": "search_offers"}
{"type": "tool_call_end", "tool_id": "call_abc", "duration_ms": 1250}
{"type": "completed", "total_events": 45}

Components

The enabled_components field controls which features are active:

• offer-list - Offer searching and listing
• prompt-suggestion - Generate follow-up prompts
• general-instructions - General behavior enhancements

Send an empty array [] to disable all components.

Localization

Set locale to “es-419” for Spanish responses:

curl -X POST http://localhost:8000/agent/stream \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Hola"}],
    "agent_id": "conversational",
    "locale": "es-419",
    "enabled_components": []
  }'

The agent will respond in Spanish.

Error Handling

HTTP errors:

• 404 - Prompt file not found
• 422 - Invalid request body
• 500 - Server error

Stream errors are sent as events:

{"type": "error", "error": "Model timeout", "code": "generation_error"}

Notes

• First token typically arrives in 100-500ms
• Tool calls add 1-3 seconds depending on the operation
• Default timeout is 30 seconds
• No rate limiting currently enforced
• Keep userId consistent for personalized results
• Location coordinates improve offer relevance

Examples

All components:

curl -X POST http://localhost:8000/agent/stream \
  -H "Content-Type: application/json" \
  -H "userId: user123" \
  -d '{
    "messages": [{"role": "user", "content": "Help me shop"}],
    "agent_id": "conversational",
    "enabled_components": ["offer-list", "prompt-suggestion", "general-instructions"]
  }'

Spanish with location:

curl -X POST http://localhost:8000/agent/stream \
  -H "Content-Type: application/json" \
  -H "userId: user123" \
  -d '{
    "messages": [{"role": "user", "content": "Busco ofertas de pizza"}],
    "agent_id": "conversational",
    "locale": "es-419",
    "latitude": 41.8781,
    "longitude": -87.6298,
    "enabled_components": ["offer-list"]
  }'