---
title: "Create a new debug chat session"
method: POST
path: "/v1/agents/{agentId}/debug-chat"
tags: ["Debug Chat"]
---

# Create a new debug chat session

`POST /v1/agents/{agentId}/debug-chat`

## Request body

- CreateDebugChatBody — Starting parameters for a debug chat session: which agent variant, which language codes, and which environment to run in.
  - `clientEnv` string, required — Client environment (sandbox, pre-release, live)
  - `asrLangCode` string — ASR language code (e.g. en-US). Defaults to server config.
  - `ttsLangCode` string — TTS language code (e.g. en-US). Defaults to server config.
  - `conversationId` string — Custom conversation ID. Auto-generated if omitted.
  - `variantId` string — Variant ID to use
  - `channel` string — Channel type (e.g. chat.polyai)
  - `integrationAttributes` object — Custom attributes accessible via conv.integration_attributes in project functions

## Response `201`

Successful response

- DebugChatResponse — A chat turn's result: the agent's reply text, the conversation's updated state, and whether the conversation has ended.
  - `conversationId` string, required
  - `userInput` string, required
  - `response` string, required
  - `metadata` ChatMetadataResponse, required — Metadata returned with each chat response.
    - `state` object, required
    - `currentNode` string, required
    - `nodeTrace` string[], required
    - `metrics` object, required
    - `functionEvents` unknown[], required
      - unknown
    - `handoffDestination` string
    - `retrievedTopics` string[]
    - `retrievedSources` string[]
    - `citedTopic` string
    - `inFlow` string
    - `inStep` string
    - `llmRequests` object[]
    - `asrLangCode` string
    - `ttsLangCode` string
  - `conversationEnded` boolean, required
  - `delayedResponse` boolean, required

## Other responses

- `400` — Validation error
- `401` — Unauthorized – missing or invalid API key
- `403` — Forbidden – insufficient permissions

---

[API](https://skmtc.net/poly/apis/polyai-agents-api.md) · [All operations](https://skmtc.net/poly/apis/polyai-agents-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/poly/polyai-agents-api/revisions/76f3c606e395/schema)