> ## Documentation Index > Fetch the complete documentation index at: https://docs.retellai.com/llms.txt > Use this file to discover all available pages before exploring further. # Agent Playground Completion > 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. ## OpenAPI ````yaml openapi-final post /agent-playground-completion/{agent_id} openapi: 3.0.3 info: title: Retell SDK version: 3.0.0 contact: name: Retell Support url: https://www.retellai.com/ email: support@retellai.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.retellai.com description: The production server. security: - api_key: [] paths: /agent-playground-completion/{agent_id}: post: description: >- 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. operationId: agentPlaygroundCompletion parameters: - name: agent_id in: path required: true schema: type: string description: Unique id of the agent. - name: version in: query required: false schema: $ref: '#/components/schemas/AgentVersionReference' description: Agent version to use. Defaults to latest. requestBody: required: true content: application/json: schema: type: object required: - messages properties: messages: type: array items: $ref: '#/components/schemas/ChatMessageInput' description: >- Full conversation history, same shape as chat completion messages. message_id and created_timestamp are optional — server generates them if omitted. 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: type: object additionalProperties: type: string description: Key-value pairs for dynamic variable substitution. example: customer_name: John Smith customer_phone: 444-223-3564 tool_mocks: type: array items: $ref: '#/components/schemas/ToolMock' description: >- Optional mock responses for tools. When provided, the agent uses these instead of executing real tool calls. current_state: type: string description: >- Current state name for retell-llm agents. Used to resume from a specific state. example: greeting current_node_id: type: string description: >- 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: type: string description: >- Conversation flow component id. Required when current_node_id refers to a node within a component. example: component_xyz789 responses: '200': description: Successfully generated playground completion. content: application/json: schema: type: object required: - messages properties: messages: type: array items: $ref: '#/components/schemas/MessageOrToolCall' description: >- New messages generated by the agent. Same shape as chat completion response messages. Does not include the input messages. current_state: type: string description: Current state name (retell-llm agents). example: greeting current_node_id: type: string description: Current node id (conversation-flow agents). example: node_abc123 dynamic_variables: type: object additionalProperties: type: string description: Updated dynamic variables after this turn. example: customer_name: John Doe call_ended: type: boolean description: Whether the agent ended the conversation. example: false knowledge_base_retrieved_contents: type: array items: type: string description: Knowledge base chunks retrieved for this turn. example: - >- Our business hours are Monday through Friday, 9am to 5pm. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '422': $ref: '#/components/responses/UnprocessableContent' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' x-codeSamples: - lang: JavaScript source: |- 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); - lang: Python source: |- 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) components: schemas: AgentVersionReference: oneOf: - type: string minLength: 1 maxLength: 20 pattern: >- ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$ example: latest_published - type: integer minimum: 0 example: 1 description: >- 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. ChatMessageInput: description: >- Same shape as chat completion messages. message_id and created_timestamp are optional — server generates them if omitted. oneOf: - $ref: '#/components/schemas/MessageBase' - $ref: '#/components/schemas/ToolCallInvocationMessageBase' - $ref: '#/components/schemas/ToolCallResultMessageBase' - $ref: '#/components/schemas/NodeTransitionMessageBase' - $ref: '#/components/schemas/StateTransitionMessageBase' - $ref: '#/components/schemas/InjectedMessageBase' - $ref: '#/components/schemas/SmsMessageBase' ToolMock: description: >- A fake response for one tool. During a simulation, when the LLM calls a tool whose name matches `tool_name` and whose arguments satisfy `input_match_rule`, the real tool is not run; `output` is returned to the LLM instead. This keeps runs deterministic and avoids calling live integrations. A tool call that matches no mock falls through to the real tool. type: object required: - tool_name - input_match_rule - output properties: tool_name: type: string description: >- The tool's function name, not the tool ID, i.e. the name the LLM uses when it calls the tool (for example `check_availability_cal`, `book_appointment_cal`, or the name you gave a custom function). input_match_rule: $ref: '#/components/schemas/ToolMockInputMatchRule' description: Decides which calls to this tool the mock applies to. output: type: string maxLength: 15000 description: >- The tool result fed back to the LLM in place of the real tool's output. Should be a JSON string, the same shape the real tool would return. result: type: boolean nullable: true description: >- For tool calls like transfer_call that require a boolean result. Optional for most tools. MessageOrToolCall: oneOf: - $ref: '#/components/schemas/Message' - $ref: '#/components/schemas/ToolCallInvocationMessage' - $ref: '#/components/schemas/ToolCallResultMessage' - $ref: '#/components/schemas/NodeTransitionMessage' - $ref: '#/components/schemas/StateTransitionMessage' - $ref: '#/components/schemas/InjectedMessage' - $ref: '#/components/schemas/SmsMessage' MessageBase: type: object required: - role - content properties: message_id: type: string example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 description: Unique id of the message role: type: string enum: - agent - user description: Documents whether this message is sent by agent or user. example: agent content: type: string description: Content of the message example: hi how are you doing? created_timestamp: type: integer description: Create timestamp of the message example: 1703302428855 ToolCallInvocationMessageBase: type: object required: - role - tool_call_id - name - arguments properties: message_id: type: string example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 description: Unique id of the message role: type: string enum: - tool_call_invocation description: This is a tool call invocation. tool_call_id: type: string description: Tool call id, globally unique. name: type: string description: Name of the function in this tool call. arguments: type: string description: Arguments for this tool call, it's a stringified JSON object. thought_signature: type: string description: >- Optional thought signature from Google Gemini thinking models. This is used internally to maintain reasoning chain in multi-turn function calling. created_timestamp: type: integer description: Create timestamp of the message example: 1703302428855 ToolCallResultMessageBase: type: object required: - role - tool_call_id - content properties: message_id: type: string example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 description: Unique id of the message role: type: string enum: - tool_call_result description: This is the result of a tool call. tool_call_id: type: string description: Tool call id, globally unique. content: type: string description: Result of the tool call, can be a string, a stringified json, etc. successful: type: boolean description: Whether the tool call was successful. created_timestamp: type: integer description: Create timestamp of the message example: 1703302428855 NodeTransitionMessageBase: type: object required: - role properties: message_id: type: string example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 description: Unique id of the message role: type: string enum: - node_transition description: This is a node transition. former_node_id: type: string description: Former node id former_node_name: type: string description: Former node name new_node_id: type: string description: New node id new_node_name: type: string description: New node name transition_type: type: string enum: - global - global_go_back - interrupt_go_back - normal description: >- 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: type: integer description: Create timestamp of the message example: 1703302428855 StateTransitionMessageBase: type: object required: - role properties: message_id: type: string example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 description: Unique id of the message role: type: string enum: - state_transition description: This is a state transition. former_state_name: type: string description: Former state name new_state_name: type: string description: New state name created_timestamp: type: integer description: Create timestamp of the message example: 1703302428855 InjectedMessageBase: type: object required: - role - content properties: message_id: type: string example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 description: Unique id of the message role: type: string enum: - injected description: >- External context injected into the conversation via the update-live-call API. Not spoken by either party. content: type: string description: The injected context text. example: Customer just opened a support ticket about billing. created_timestamp: type: integer description: Create timestamp of the message example: 1703302428855 SmsMessageBase: type: object required: - role - content properties: message_id: type: string example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 description: Unique id of the message role: type: string enum: - sms description: >- SMS message exchanged during the call (for example received from the user). Woven into the transcript and shown to the agent, but not part of the spoken conversation. content: type: string description: Text content of the SMS message. example: Here is the photo you asked for. multimedia: type: array items: $ref: '#/components/schemas/SmsMultimediaItem' description: >- Multimedia attachments (MMS). Display only; not relayed into the spoken conversation. created_timestamp: type: integer description: Create timestamp of the message example: 1703302428855 ToolMockInputMatchRule: description: >- Decides which calls to the tool this mock applies to, based on the arguments the LLM passes to the tool. oneOf: - type: object required: - type properties: type: type: string enum: - any description: >- Match every call to the tool, no matter what arguments were passed. Use this for a catch-all mock. - type: object required: - type - args properties: type: type: string enum: - partial_match description: >- Match only calls whose arguments contain the values listed in `args`. args: type: object description: >- Argument values the call must have to match. Only the fields you list here are checked, and each must equal the value in the actual call. Extra fields in the call are ignored, so this is a subset match. Message: allOf: - $ref: '#/components/schemas/MessageBase' - required: - message_id - created_timestamp ToolCallInvocationMessage: allOf: - $ref: '#/components/schemas/ToolCallInvocationMessageBase' - required: - message_id - created_timestamp ToolCallResultMessage: allOf: - $ref: '#/components/schemas/ToolCallResultMessageBase' - required: - message_id - created_timestamp NodeTransitionMessage: allOf: - $ref: '#/components/schemas/NodeTransitionMessageBase' - required: - message_id - created_timestamp StateTransitionMessage: allOf: - $ref: '#/components/schemas/StateTransitionMessageBase' - required: - message_id - created_timestamp InjectedMessage: allOf: - $ref: '#/components/schemas/InjectedMessageBase' - required: - message_id - created_timestamp SmsMessage: allOf: - $ref: '#/components/schemas/SmsMessageBase' - required: - message_id - created_timestamp SmsMultimediaItem: type: object required: - url properties: url: type: string description: URL of the multimedia attachment. summary: type: string description: Optional textual summary of the attachment. responses: BadRequest: description: Bad Request content: application/json: schema: type: object properties: status: type: string enum: - error message: type: string example: Invalid request format, please check API reference. Unauthorized: description: Unauthorized content: application/json: schema: type: object properties: status: type: string enum: - error message: type: string example: API key is missing or invalid. PaymentRequired: description: Payment Required content: application/json: schema: type: object properties: status: type: string enum: - error message: type: string example: Trial has ended, please add payment method. UnprocessableContent: description: Unprocessable Content content: application/json: schema: type: object properties: status: type: string enum: - error message: type: string example: Cannot find requested asset under given api key. TooManyRequests: description: Too Many Requests content: application/json: schema: type: object properties: status: type: string enum: - error message: type: string example: Account rate limited, please throttle your requests. InternalServerError: description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error message: type: string example: An unexpected server error occurred. securitySchemes: api_key: type: http scheme: bearer bearerFormat: string description: >- Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY" ````