Start a chat session with an agent

Begin a chat session with an agent. When a user submits a message, the agent responds using the language model and the associated tools. This API is stateless, but you can continue conversations by including the cursor from the previous response in subsequent requests. Providing the cursor allows the agent to maintain the context of the conversation and deliver more accurate responses. When the cursor is provided, there is no need to include the previous message history in the messages field.

NOTE: Cursors are short-lived and may expire. Clients should not cache cursors or rely on them being available long-term.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
header Parameters
content-type
required
string (Content-Type)
Request Body schema: application/json
required
Array of objects (Actions) <= 10 items

Custom tool calls that a client can inject.

agentExternalId
string (Agentexternalid) ^[^\x00]{1,128}$

An external ID that uniquely identifies the agent.

agentId
string (Agentid) ^[^\x00]{1,128}$
Deprecated

Deprecated: Use AgentExternalId instead. This field uniquely identifies the agent, but is deprecated and will be removed in a future release. If both AgentId and AgentExternalId are provided, AgentExternalId takes precedence.

cursor
string (Cursor)

The cursor for continuing a multi-turn chat session. To maintain conversational context, this opaque string must be copied from the previous API response and passed in the next request. The cursor represents the server-side state and should be treated as ephemeral; do not modify or store it. To start a new conversation, this field should be omitted.

required
Array of any (Messages) [ 1 .. 1000 ] items

A list of one or multiple input items for the agent, which include various content types used to generate a response.

Responses
200

Successful Response

400

The response for a failed request.

post/ai/agents/chat
Request samples
application/json
{
  • "actions": [
    • {
      }
    ],
  • "agentExternalId": "string",
  • "agentId": "string",
  • "cursor": "string",
  • "messages": [
    • {
      }
    ]
}
Response samples
application/json
{
  • "agentExternalId": "string",
  • "agentId": "string",
  • "response": {
    • "cursor": "string",
    • "messages": [
      ],
    • "type": "result"
    }
}
➔ Next to Document AI / Ask questions about one or more documents.