Create Call

POST /api/v1/agents/{id}/call

Send one conversation turn to an online connected agent

Python

import requests

url = "https://app.langwatch.ai/api/v1/agents/{id}/call"

payload = { "messages": [{ "role": "<string>" }] }
headers = {
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

200

{
  "output": "<string>",
  "instance": {
    "hostname": "<string>",
    "label": "<string>"
  },
  "durationMs": 123,
  "session": "<unknown>",
  "state": {}
}

Authorizations

X-Auth-Token · string · header · required

Project API key for sending traces and accessing project-scoped resources. Format: sk-lw-... (no underscore). Obtain one by creating a project via the Admin API or the LangWatch UI.

Path Parameters

id · string · required

The agent id.

Minimum string length: 1

Body

application/json

messages · object[] · required

The whole conversation so far, OpenAI style.

Show child attributes

newMessages · object[]

The messages added since the agent's last turn. Defaults to the last message.

Show child attributes

threadId · string

The conversation id. Turns of one conversation share it; a new id starts a new one.

Maximum string length: 255

params · object

Run parameter values by name, as JSON scalars.

Show child attributes

session · any

The session the agent returned on its previous turn of this conversation, echoed back as is.

traceparent · string

The W3C trace context the agent adopts, so its spans join this turn's trace.

Maximum string length: 255

run · object

The simulation run this turn belongs to, if any.

Show child attributes

kind · enum<string>

A turn, or a scenario run's setup or teardown hook. Defaults to a turn.

Available options: turn, setup, teardown

state · object | null

The scenario run's test data: what setup returned, or a turn's latest update.

Show child attributes

timeoutMs · integer

A setup or teardown hook's budget in milliseconds. A turn runs under the agent's own timeout.

Required range: x <= 300000

Response

200 - application/json

Success

output · string object object[] · required

What the function answered: text, one message, or a list of messages.

instance · object · required

Show child attributes

durationMs · number · required

session · any

The agent's per-conversation memory, to send on the next turn.

state · object | null

Setup's state, a turn's state update, or the object teardown returned.

Show child attributes