Skip to main content
Test your custom chat agents by hosting them in a sandbox environment. UserTrace will interact with your API using the OpenAI Chat Completions format.

​
API Requirements

Your sandbox must expose an API endpoint compatible with OpenAI’s Chat Completions format, plus a health check endpoint.

​
1. Chat Completions Endpoint

Endpoint: POST /v1/chat/completions Request Format: 
{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful customer service agent."
    },
    {
      "role": "user", 
      "content": "I need help with my order #12345"
    }
  ],
  "user_id": "sim_user_abc123",
  "session_id": "session_xyz789",
  "metadata": {
    "scenario_id": "financial_stress_delivery",
    "persona": "delivery_worker_bengaluru",
    "time_of_day": "morning_rush"
  }
}
Response Format: 
{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I'd be happy to help you with your order. Let me look up order #12345 for you."
      },
      "finish_reason": "stop"
    }
  ],
  "session_id": "session_xyz789",
  "chat_id": "chat_456def",
  "metadata": {
    "agent_confidence": 0.95,
    "response_time_ms": 1200,
    "tools_used": ["order_lookup"]
  },
  "evaluation_metadata": {
    "order_found": true,
    "tone": "empathetic",
    "resolution_step": 1,
    "customer_acknowledged": true
  }
}

​
2. Health Check Endpoint

Endpoint: GET /health Request: 
curl -X GET https://your-sandbox.com/health
Response Format: 
{
  "status": "healthy",
  "timestamp": "2024-01-21T10:30:00Z",
  "version": "1.0.0",
  "uptime": 3600
}

​
Advanced Configuration

​
User Management (Optional)

If your agent requires user-specific contexts or session management, we can create users at the start of each simulation session. Endpoint: POST /users Request Format: 
{
  "user_id": "sim_user_abc123",
  "metadata": {
    "scenario_id": "financial_stress_delivery",
    "persona": "delivery_worker_bengaluru",
    "session_type": "morning_rush"
  }
}
Response Format: 
{
  "user_id": "sim_user_abc123", 
  "created_at": "2024-01-21T10:30:00Z",
  "status": "active"
}

​
Optional Parameters

user_id and session_id are optional in requests. If your agent doesn’t require session management, you can omit them. metadata is optional and can contain any scenario or context information your agent needs. Request with minimal parameters: 
{
  "messages": [
    {
      "role": "user",
      "content": "Hello, I need help"
    }
  ]
}
Request with full parameters: 
{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful customer service agent."
    },
    {
      "role": "user",
      "content": "I need help with my order #12345"
    }
  ],
  "user_id": "sim_user_abc123",
  "session_id": "session_xyz789",
  "metadata": {
    "scenario_id": "financial_stress_delivery",
    "persona": "delivery_worker_bengaluru",
    "stress_level": "high",
    "location": "bengaluru"
  }
}

​
Implementation Guide

​
1. Set Up Your Sandbox

Deploy your chat agent to a publicly accessible endpoint with HTTPS support. Required Headers:
  • Content-Type: application/json
  • Authorization: Bearer <your-api-key> (best practice for security)

​
2. Test Your Endpoints

Chat Completions Test: 
curl -X POST https://your-sandbox.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "messages": [
      {"role": "user", "content": "Hello, test message"}
    ],
    "user_id": "test_user_123",
    "session_id": "test_session_456"
  }'
Health Check Test: 
curl -X GET https://your-sandbox.com/health

​
3. Configure in UserTrace

  1. Add your sandbox URL in the UserTrace dashboard
  2. Set authentication if required (API keys, tokens)
  3. Enable user management if your agent needs user contexts
  4. Configure metadata passing for state-dependent scenarios

​
Error Handling

Your API should return appropriate HTTP status codes: 400 Bad Request: 
{
  "error": {
    "message": "Invalid request format",
    "type": "invalid_request_error",
    "code": "bad_request"
  }
}
500 Internal Server Error: 
{
  "error": {
    "message": "Internal server error",
    "type": "internal_error", 
    "code": "server_error"
  }
}
429 Rate Limit: 
{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

​
Best Practices

Performance

Response Optimization• Target < 5 second response times • Support 100 RPS for parallel simulations • Implement proper error handling • Add request/response logging

Security

API Security• Use HTTPS endpoints only • Implement rate limiting • Validate all input data

​
Tool Calling Support

For agents that use function calling, the simulated user will send simple requests without tool definitions. Your agent must handle all tool calling internally - execute the necessary functions, get the results, and include the complete sequence of tool calls and responses in your response. The evaluator will use this information to evaluate your agent’s tool usage and decision-making. Request from Simulated User: 
{
  "messages": [
    {
      "role": "user",
      "content": "What's the status of my order #12345?"
    }
  ],
  "user_id": "sim_user_abc123",
  "session_id": "session_xyz789"
}
Response with Tool Call and Results: 
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "I found your order! Order #12345 is currently being prepared and will be shipped within 2 hours.",
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_order_status",
              "arguments": "{\"order_id\": \"12345\"}",
              "result": {
                "order_id": "12345",
                "status": "preparing",
                "estimated_ship_time": "2 hours",
                "tracking_number": null
              }
            }
          }
        ]
      }
    }
  ],
  "session_id": "session_xyz789",
  "chat_id": "chat_456def",
  "evaluation_metadata": {
    "tool_called": "get_order_status",
    "tool_success": true,
    "response_included_status": true,
    "customer_informed": true
  }
}

​
Common Integration Patterns

  • RAG Systems: Pass document context in system messages
  • Multi-Agent: Route requests based on message content
  • Memory Integration: Use user metadata for conversation history
  • External APIs: Include tool calls for third-party integrations
Need help with integration? Our team can assist with custom requirements and complex architectures. Contact [email protected].Next Steps: Once configured, create test scenarios and run simulations to validate your agent.