Agent Playground Completion

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, I'd like to check my appointment.", role: 'user' },
    { content: 'Sure! Could you please provide your name?', role: 'agent' },
    { content: 'My name is John Smith.', role: 'user' },
  ],
});

console.log(response.current_node_id);

import os
from retell import Retell

client = Retell(
    api_key=os.environ.get("RETELL_API_KEY"),  # This is the default and can be omitted
)
response = client.playground.completion(
    agent_id="agent_id",
    messages=[{
        "content": "Hi, I'd like to check my appointment.",
        "role": "user",
    }, {
        "content": "Sure! Could you please provide your name?",
        "role": "agent",
    }, {
        "content": "My name is John Smith.",
        "role": "user",
    }],
)
print(response.current_node_id)

curl --request POST \
  --url https://api.retellai.com/agent-playground-completion/{agent_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "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"
  },
  "tool_mocks": [
    {
      "input_match_rule": {
        "type": "any"
      },
      "output": "<string>",
      "tool_name": "<string>",
      "node_id": "<string>",
      "result": true
    }
  ],
  "current_state": "greeting",
  "current_node_id": "start-node-abc123",
  "component_id": "component_xyz789"
}
EOF

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.retellai.com/agent-playground-completion/{agent_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ],
    'tool_mocks' => [
        [
                'input_match_rule' => [
                                'type' => 'any'
                ],
                'output' => '<string>',
                'tool_name' => '<string>',
                'node_id' => '<string>',
                'result' => true
        ]
    ],
    'current_state' => 'greeting',
    'current_node_id' => 'start-node-abc123',
    'component_id' => 'component_xyz789'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.retellai.com/agent-playground-completion/{agent_id}"

	payload := strings.NewReader("{\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Hi, I'd like to check my appointment.\"\n    },\n    {\n      \"role\": \"agent\",\n      \"content\": \"Sure! Could you please provide your name?\"\n    },\n    {\n      \"role\": \"user\",\n      \"content\": \"My name is John Smith.\"\n    }\n  ],\n  \"dynamic_variables\": {\n    \"customer_name\": \"John Smith\",\n    \"customer_phone\": \"444-223-3564\"\n  },\n  \"tool_mocks\": [\n    {\n      \"input_match_rule\": {\n        \"type\": \"any\"\n      },\n      \"output\": \"<string>\",\n      \"tool_name\": \"<string>\",\n      \"node_id\": \"<string>\",\n      \"result\": true\n    }\n  ],\n  \"current_state\": \"greeting\",\n  \"current_node_id\": \"start-node-abc123\",\n  \"component_id\": \"component_xyz789\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.retellai.com/agent-playground-completion/{agent_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Hi, I'd like to check my appointment.\"\n    },\n    {\n      \"role\": \"agent\",\n      \"content\": \"Sure! Could you please provide your name?\"\n    },\n    {\n      \"role\": \"user\",\n      \"content\": \"My name is John Smith.\"\n    }\n  ],\n  \"dynamic_variables\": {\n    \"customer_name\": \"John Smith\",\n    \"customer_phone\": \"444-223-3564\"\n  },\n  \"tool_mocks\": [\n    {\n      \"input_match_rule\": {\n        \"type\": \"any\"\n      },\n      \"output\": \"<string>\",\n      \"tool_name\": \"<string>\",\n      \"node_id\": \"<string>\",\n      \"result\": true\n    }\n  ],\n  \"current_state\": \"greeting\",\n  \"current_node_id\": \"start-node-abc123\",\n  \"component_id\": \"component_xyz789\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.retellai.com/agent-playground-completion/{agent_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Hi, I'd like to check my appointment.\"\n    },\n    {\n      \"role\": \"agent\",\n      \"content\": \"Sure! Could you please provide your name?\"\n    },\n    {\n      \"role\": \"user\",\n      \"content\": \"My name is John Smith.\"\n    }\n  ],\n  \"dynamic_variables\": {\n    \"customer_name\": \"John Smith\",\n    \"customer_phone\": \"444-223-3564\"\n  },\n  \"tool_mocks\": [\n    {\n      \"input_match_rule\": {\n        \"type\": \"any\"\n      },\n      \"output\": \"<string>\",\n      \"tool_name\": \"<string>\",\n      \"node_id\": \"<string>\",\n      \"result\": true\n    }\n  ],\n  \"current_state\": \"greeting\",\n  \"current_node_id\": \"start-node-abc123\",\n  \"component_id\": \"component_xyz789\"\n}"

response = http.request(request)
puts response.read_body

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

{
  "status": "error",
  "message": "Invalid request format, please check API reference."
}

{
  "status": "error",
  "message": "API key is missing or invalid."
}

{
  "status": "error",
  "message": "Trial has ended, please add payment method."
}

{
  "status": "error",
  "message": "Cannot find requested asset under given api key."
}

{
  "status": "error",
  "message": "Account rate limited, please throttle your requests."
}

{
  "status": "error",
  "message": "An unexpected server error occurred."
}

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

Agent version to use. Defaults to latest. 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.

Required string length: 1 - 20

Pattern: ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$

Example:

"latest_published"

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.

Show child attributes

Example:

[
  {
    "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

object

Key-value pairs for dynamic variable substitution.

Show child attributes

Example:

{
  "customer_name": "John Smith",
  "customer_phone": "444-223-3564"
}

tool_mocks

object[]

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

Show child attributes

current_state

string

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

Example:

"greeting"

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.

Example:

"start-node-abc123"

component_id

string

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

Example:

"component_xyz789"

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.

Show child attributes

current_state

string

Current state name (retell-llm agents).

Example:

"greeting"

current_node_id

string

Current node id (conversation-flow agents).

Example:

"node_abc123"

dynamic_variables

object

Updated dynamic variables after this turn.

Show child attributes

Example:

{ "customer_name": "John Doe" }

call_ended

boolean

Whether the agent ended the conversation.

Example:

false

knowledge_base_retrieved_contents

string[]

Knowledge base chunks retrieved for this turn.

Example:

[
  "Our business hours are Monday through Friday, 9am to 5pm."
]

⌘I

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, I'd like to check my appointment.", role: 'user' },
    { content: 'Sure! Could you please provide your name?', role: 'agent' },
    { content: 'My name is John Smith.', role: 'user' },
  ],
});

console.log(response.current_node_id);

import os
from retell import Retell

client = Retell(
    api_key=os.environ.get("RETELL_API_KEY"),  # This is the default and can be omitted
)
response = client.playground.completion(
    agent_id="agent_id",
    messages=[{
        "content": "Hi, I'd like to check my appointment.",
        "role": "user",
    }, {
        "content": "Sure! Could you please provide your name?",
        "role": "agent",
    }, {
        "content": "My name is John Smith.",
        "role": "user",
    }],
)
print(response.current_node_id)

curl --request POST \
  --url https://api.retellai.com/agent-playground-completion/{agent_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "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"
  },
  "tool_mocks": [
    {
      "input_match_rule": {
        "type": "any"
      },
      "output": "<string>",
      "tool_name": "<string>",
      "node_id": "<string>",
      "result": true
    }
  ],
  "current_state": "greeting",
  "current_node_id": "start-node-abc123",
  "component_id": "component_xyz789"
}
EOF

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.retellai.com/agent-playground-completion/{agent_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ],
    'tool_mocks' => [
        [
                'input_match_rule' => [
                                'type' => 'any'
                ],
                'output' => '<string>',
                'tool_name' => '<string>',
                'node_id' => '<string>',
                'result' => true
        ]
    ],
    'current_state' => 'greeting',
    'current_node_id' => 'start-node-abc123',
    'component_id' => 'component_xyz789'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.retellai.com/agent-playground-completion/{agent_id}"

	payload := strings.NewReader("{\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Hi, I'd like to check my appointment.\"\n    },\n    {\n      \"role\": \"agent\",\n      \"content\": \"Sure! Could you please provide your name?\"\n    },\n    {\n      \"role\": \"user\",\n      \"content\": \"My name is John Smith.\"\n    }\n  ],\n  \"dynamic_variables\": {\n    \"customer_name\": \"John Smith\",\n    \"customer_phone\": \"444-223-3564\"\n  },\n  \"tool_mocks\": [\n    {\n      \"input_match_rule\": {\n        \"type\": \"any\"\n      },\n      \"output\": \"<string>\",\n      \"tool_name\": \"<string>\",\n      \"node_id\": \"<string>\",\n      \"result\": true\n    }\n  ],\n  \"current_state\": \"greeting\",\n  \"current_node_id\": \"start-node-abc123\",\n  \"component_id\": \"component_xyz789\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.retellai.com/agent-playground-completion/{agent_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Hi, I'd like to check my appointment.\"\n    },\n    {\n      \"role\": \"agent\",\n      \"content\": \"Sure! Could you please provide your name?\"\n    },\n    {\n      \"role\": \"user\",\n      \"content\": \"My name is John Smith.\"\n    }\n  ],\n  \"dynamic_variables\": {\n    \"customer_name\": \"John Smith\",\n    \"customer_phone\": \"444-223-3564\"\n  },\n  \"tool_mocks\": [\n    {\n      \"input_match_rule\": {\n        \"type\": \"any\"\n      },\n      \"output\": \"<string>\",\n      \"tool_name\": \"<string>\",\n      \"node_id\": \"<string>\",\n      \"result\": true\n    }\n  ],\n  \"current_state\": \"greeting\",\n  \"current_node_id\": \"start-node-abc123\",\n  \"component_id\": \"component_xyz789\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.retellai.com/agent-playground-completion/{agent_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Hi, I'd like to check my appointment.\"\n    },\n    {\n      \"role\": \"agent\",\n      \"content\": \"Sure! Could you please provide your name?\"\n    },\n    {\n      \"role\": \"user\",\n      \"content\": \"My name is John Smith.\"\n    }\n  ],\n  \"dynamic_variables\": {\n    \"customer_name\": \"John Smith\",\n    \"customer_phone\": \"444-223-3564\"\n  },\n  \"tool_mocks\": [\n    {\n      \"input_match_rule\": {\n        \"type\": \"any\"\n      },\n      \"output\": \"<string>\",\n      \"tool_name\": \"<string>\",\n      \"node_id\": \"<string>\",\n      \"result\": true\n    }\n  ],\n  \"current_state\": \"greeting\",\n  \"current_node_id\": \"start-node-abc123\",\n  \"component_id\": \"component_xyz789\"\n}"

response = http.request(request)
puts response.read_body

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

{
  "status": "error",
  "message": "Invalid request format, please check API reference."
}

{
  "status": "error",
  "message": "API key is missing or invalid."
}

{
  "status": "error",
  "message": "Trial has ended, please add payment method."
}

{
  "status": "error",
  "message": "Cannot find requested asset under given api key."
}

{
  "status": "error",
  "message": "Account rate limited, please throttle your requests."
}

{
  "status": "error",
  "message": "An unexpected server error occurred."
}

Call

Chat

Playground

Phone Number

Voice Agent

Chat Agent

Retell LLM Response Engine (for single / multi prompt agent)

Conversation Flow Response Engine (for conversation flow agent)

Conversation Flow Subflows

MCP Tool

Knowledge Base

Voice

Batch call

Contact

App

CRM

Test Case Definitions

Batch Tests

Test Runs

Account

Custom Telephony

Custom LLM

Agent Playground Completion

Authorizations

Path Parameters

Query Parameters

Body

Response