Sign in

v28

latestOpenAPI 3.0.3Apache 2.0raw.githubusercontent.com2026-05-2887246443.7 KB

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.

post/agent-playground-completion/{agent_id}

Path parameters

agent_idstring required

Unique id of the agent.

Query parameters

integer
OR
string
Example:1

Agent version to use. Defaults to latest.

Request body

dynamic_variablesobject

Key-value pairs for dynamic variable substitution.

current_statestring

Current state name for retell-llm agents. Used to resume from a specific state.

current_node_idstring

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_idstring

Conversation flow component id. Required when current_node_id refers to a node within a component.

Example request

{
  "messages": [
    {
      "role": "user",
      "content": "Hi, I'd like to check my appointment."
    },
    {
      "role": "agent",
      "content": "Sure! Could you please provide your name?"
    },
    {
      "role": "user",
      "content": "My name is John Smith."
    }
  ],
  "dynamic_variables": {
    "customer_name": "John Smith",
    "customer_phone": "444-223-3564"
  },
  "current_state": "greeting",
  "current_node_id": "start-node-abc123",
  "component_id": "component_xyz789"
}

Response

Successfully generated playground completion.

current_statestring

Current state name (retell-llm agents).

current_node_idstring

Current node id (conversation-flow agents).

dynamic_variablesobject

Updated dynamic variables after this turn.

call_endedboolean

Whether the agent ended the conversation.

knowledge_base_retrieved_contentsstring[]

Knowledge base chunks retrieved for this turn.

Example response

{
  "messages": [
    {
      "message_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
      "role": "agent",
      "content": "hi how are you doing?",
      "created_timestamp": 1703302428855
    }
  ],
  "current_state": "greeting",
  "current_node_id": "node_abc123",
  "dynamic_variables": {
    "customer_name": "John Doe"
  },
  "knowledge_base_retrieved_contents": [
    "Our business hours are Monday through Friday, 9am to 5pm."
  ]
}