> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getusertrace.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Chat Agent

> Test custom chat agents through API endpoints

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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```bash theme={null}
curl -X GET https://your-sandbox.com/health
```

**Response Format:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "user_id": "sim_user_abc123",
  "metadata": {
    "scenario_id": "financial_stress_delivery",
    "persona": "delivery_worker_bengaluru",
    "session_type": "morning_rush"
  }
}
```

**Response Format:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "messages": [
    {
      "role": "user",
      "content": "Hello, I need help"
    }
  ]
}
```

**Request with full parameters:**

```json theme={null}
{
  "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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```json theme={null}
{
  "error": {
    "message": "Invalid request format",
    "type": "invalid_request_error",
    "code": "bad_request"
  }
}
```

**500 Internal Server Error:**

```json theme={null}
{
  "error": {
    "message": "Internal server error",
    "type": "internal_error", 
    "code": "server_error"
  }
}
```

**429 Rate Limit:**

```json theme={null}
{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Performance" icon="zap">
    **Response Optimization**

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

  <Card title="Security" icon="shield">
    **API Security**

    • Use HTTPS endpoints only
    • Implement rate limiting
    • Validate all input data
  </Card>
</CardGroup>

## 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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

<Note>
  **Need help with integration?** Our team can assist with custom requirements and complex architectures. Contact [support@getusertrace.com](mailto:support@getusertrace.com).

  **Next Steps**: Once configured, [create test scenarios](/scenarios-generation) and [run simulations](/running-simulations) to validate your agent.
</Note>