Skip to main content
POST
/
agent-playground-completion
/
{agent_id}
JavaScript
import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted
});

const response = await client.playground.completion('agent_id', {
  messages: [{ content: 'hi how are you doing?', role: 'agent' }],
});

console.log(response.current_node_id);
{
  "messages": [
    {
      "message_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
      "role": "agent",
      "content": "hi how are you doing?",
      "created_timestamp": 1703302428855
    }
  ],
  "current_state": "<string>",
  "current_node_id": "<string>",
  "dynamic_variables": {},
  "call_ended": true,
  "knowledge_base_retrieved_contents": [
    "<string>"
  ]
}

Authorizations

Authorization
string
header
required

Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"

Path Parameters

agent_id
string
required

Unique id of the agent.

Query Parameters

version
integer

Agent version to use. Defaults to latest.

Body

application/json
messages
object[]
required

Full conversation history, same shape as chat completion messages. message_id and created_timestamp are optional — server generates them if omitted.

Same shape as chat completion messages. message_id and created_timestamp are optional — server generates them if omitted.

dynamic_variables
object

Key-value pairs for dynamic variable substitution.

tool_mocks
object[]

Optional mock responses for tools. When provided, the agent uses these instead of executing real tool calls.

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

Successfully generated playground completion.

messages
object[]
required

New messages generated by the agent. Same shape as chat completion response messages. Does not include the input messages.

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.