---
title: "POST /agent-playground-completion/{agent_id}"
method: POST
path: "/agent-playground-completion/{agent_id}"
---

# POST /agent-playground-completion/{agent_id}

`POST /agent-playground-completion/{agent_id}`

Stateless playground completion. Send the full conversation history (same shape as chat completion messages) and receive only the newly generated messages. Nothing is persisted server-side — the caller manages conversation state.

## Path parameters

- `agent_id` string, required

## Query parameters

- `version` union — Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). The string "latest" resolves to the most recently created version (the largest version number), and "latest_published" resolves to the most recently published version. When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version, latest, or latest_published is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.
  - integer
  - string

## Request body

- object
  - `messages` ChatMessageInput[], required — Full conversation history, same shape as chat completion messages. message_id and created_timestamp are optional — server generates them if omitted.
    - union — Same shape as chat completion messages. message_id and created_timestamp are optional — server generates them if omitted.
      - MessageBase
        - `message_id` string — Unique id of the message
        - `role` 'agent' | 'user', required — Documents whether this message is sent by agent or user.
        - `content` string, required — Content of the message
        - `created_timestamp` integer — Create timestamp of the message
      - ToolCallInvocationMessageBase
        - `message_id` string — Unique id of the message
        - `role` 'tool_call_invocation', required — This is a tool call invocation.
        - `tool_call_id` string, required — Tool call id, globally unique.
        - `name` string, required — Name of the function in this tool call.
        - `arguments` string, required — Arguments for this tool call, it's a stringified JSON object.
        - `thought_signature` string — Optional thought signature from Google Gemini thinking models. This is used internally to maintain reasoning chain in multi-turn function calling.
        - `created_timestamp` integer — Create timestamp of the message
      - ToolCallResultMessageBase
        - `message_id` string — Unique id of the message
        - `role` 'tool_call_result', required — This is the result of a tool call.
        - `tool_call_id` string, required — Tool call id, globally unique.
        - `content` string, required — Result of the tool call, can be a string, a stringified json, etc.
        - `successful` boolean — Whether the tool call was successful.
        - `created_timestamp` integer — Create timestamp of the message
      - NodeTransitionMessageBase
        - `message_id` string — Unique id of the message
        - `role` 'node_transition', required — This is a node transition.
        - `former_node_id` string — Former node id
        - `former_node_name` string — Former node name
        - `new_node_id` string — New node id
        - `new_node_name` string — New node name
        - `transition_type` 'global' | 'global_go_back' | 'interrupt_go_back' | 'normal' — How this node was reached. "global" means a global node transition, "global_go_back" means returning from a global node, "interrupt_go_back" means going back due to user interruption, and "normal" means a regular edge transition.
        - `created_timestamp` integer — Create timestamp of the message
      - StateTransitionMessageBase
        - `message_id` string — Unique id of the message
        - `role` 'state_transition', required — This is a state transition.
        - `former_state_name` string — Former state name
        - `new_state_name` string — New state name
        - `created_timestamp` integer — Create timestamp of the message
  - `dynamic_variables` object — Key-value pairs for dynamic variable substitution.
  - `tool_mocks` ToolMock[] — Optional mock responses for tools. When provided, the agent uses these instead of executing real tool calls.
    - `tool_name` string, required — Name of the tool to mock
    - `input_match_rule` union, required
      - object
        - `type` 'any', required — Match any input of the tool
      - object
        - `type` 'partial_match', required — Match only calls with specific arguments
        - `args` object, required — Arguments to match. Only provided fields will be checked
    - `output` string, required — The output of the tool call that will be fed into the LLM. Should be a JSON string.
    - `result` boolean, nullable — For tool calls like transfer_call that require a boolean result. Optional for most tools.
  - `current_state` string — Current state name for retell-llm agents. Used to resume from a specific state.
  - `current_node_id` string — Current node id for conversation-flow agents. Used to resume from a specific node. Must be provided together with component_id when testing components.
  - `component_id` string — Conversation flow component id. Required when current_node_id refers to a node within a component.

## Response `200`

Successfully generated playground completion.

- object
  - `messages` MessageOrToolCall[], required — New messages generated by the agent. Same shape as chat completion response messages. Does not include the input messages.
    - union
      - Message
        - `message_id` string, required — Unique id of the message
        - `role` 'agent' | 'user', required — Documents whether this message is sent by agent or user.
        - `content` string, required — Content of the message
        - `created_timestamp` integer, required — Create timestamp of the message
      - ToolCallInvocationMessage
        - `message_id` string, required — Unique id of the message
        - `role` 'tool_call_invocation', required — This is a tool call invocation.
        - `tool_call_id` string, required — Tool call id, globally unique.
        - `name` string, required — Name of the function in this tool call.
        - `arguments` string, required — Arguments for this tool call, it's a stringified JSON object.
        - `thought_signature` string — Optional thought signature from Google Gemini thinking models. This is used internally to maintain reasoning chain in multi-turn function calling.
        - `created_timestamp` integer, required — Create timestamp of the message
      - ToolCallResultMessage
        - `message_id` string, required — Unique id of the message
        - `role` 'tool_call_result', required — This is the result of a tool call.
        - `tool_call_id` string, required — Tool call id, globally unique.
        - `content` string, required — Result of the tool call, can be a string, a stringified json, etc.
        - `successful` boolean — Whether the tool call was successful.
        - `created_timestamp` integer, required — Create timestamp of the message
      - NodeTransitionMessage
        - `message_id` string, required — Unique id of the message
        - `role` 'node_transition', required — This is a node transition.
        - `former_node_id` string — Former node id
        - `former_node_name` string — Former node name
        - `new_node_id` string — New node id
        - `new_node_name` string — New node name
        - `transition_type` 'global' | 'global_go_back' | 'interrupt_go_back' | 'normal' — How this node was reached. "global" means a global node transition, "global_go_back" means returning from a global node, "interrupt_go_back" means going back due to user interruption, and "normal" means a regular edge transition.
        - `created_timestamp` integer, required — Create timestamp of the message
      - StateTransitionMessage
        - `message_id` string, required — Unique id of the message
        - `role` 'state_transition', required — This is a state transition.
        - `former_state_name` string — Former state name
        - `new_state_name` string — New state name
        - `created_timestamp` integer, required — Create timestamp of the message
  - `current_state` string — Current state name (retell-llm agents).
  - `current_node_id` string — Current node id (conversation-flow agents).
  - `dynamic_variables` object — Updated dynamic variables after this turn.
  - `call_ended` boolean — Whether the agent ended the conversation.
  - `knowledge_base_retrieved_contents` string[] — Knowledge base chunks retrieved for this turn.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `402` — Payment Required
- `422` — Unprocessable Content
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.net/retellai/apis/retell-sdk.md) · [All operations](https://skmtc.net/retellai/apis/retell-sdk/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/retellai/retell-sdk/versions/2a182bedbfc5/schema)