Ctrlk
CommunitySupport PortalYouTubeFree trialSign Up!
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Agent Chat

Chat With Agents

Starting agent chat

post

Allows for communication with Emporix agents. Conversational continuity requires both the session-id header and enabledMemory set to true on the agent. Collaborations configured in agentCollaborations run in the same session.

When the request includes attachments, each attachments[].attachmentId must reference a file already uploaded in this session. Send the upload sessionId as the session-id header. The attachment must already be attached to the agentId in the request body. After a file upload, send that same path agentId in the chat body. After reuse, send the target agent's path agentId in the chat body. If they differ, the request returns 400. To use the file with a different agent, first assign the attachment to that agent with attachmentId on POST /ai-service/{tenant}/agentic/{agentId}/attachments using the target agentId in the path, then chat with that target agent.

Required scopes
This endpoint requires the following scopes:
  • : Needed to execute agentic chat.
  • : Needed to execute agentic chat by customers.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

Header parameters
session-idstring · uuidOptional

Optional UUID of the AI Service chat session. If omitted, the system generates one.

Reuse the same value on later chat and attachment calls to continue the same session, access attachments from that session, and keep conversational memory when enabledMemory is true on the agent. A new value starts a new session.

On Starting agent chat, the value is sessionId in the JSON response. On Starting agent chat stream, the value is session_id in the SSE done event. When a chat request includes attachments, send the same value returned as sessionId from the upload or from assigning existing media. Do not send sessionId in the request body. Omitting session-id when you assign media starts a new session and returns that sessionId.

Body
agentIdstringRequired

Unique identifier of the agent.

messagestringRequired

The user message to the agent.

Responses
200

Chat response.

application/json
agentIdstringOptional

Unique identifier of the agent.

agentTypestring · enumOptional

Type of the agent handling the request.

Possible values:
sessionIdstringOptional

Unique identifier of the session. Send this value back as the session-id header on later chat and attachment calls.

messagestringOptional

Agent message.

post/ai-service/{tenant}/agentic/chat
POST /ai-service/{tenant}/agentic/chat HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 78

{
  "agentId": "complaint-agent",
  "message": "Find a product with \"EON1243\" code"
}
[
  {
    "agentId": "complaint-agent",
    "agentType": "complaint",
    "message": "Found an order with its details.",
    "sessionId": "fe91d168-4ce9-4b4d-8451-0029035b34a5"
  }
]

Starting agent chat stream

post

Allows for communication with Emporix agents using a Server-Sent Events stream. Conversational continuity requires both the session-id header and enabledMemory set to true on the agent. Collaborations configured in agentCollaborations run in the same session.

When the request includes attachments, each attachments[].attachmentId must reference a file already uploaded in this session. Send the upload sessionId as the session-id header. The attachment must already be attached to the agentId in the request body. After a file upload, send that same path agentId in the chat body. After reuse, send the target agent's path agentId in the chat body. If they differ, the request returns 400. To use the file with a different agent, first assign the attachment to that agent with attachmentId on POST /ai-service/{tenant}/agentic/{agentId}/attachments using the target agentId in the path, then chat with that target agent.

The response Content-Type is text/event-stream. Each frame uses an SSE event name and a JSON object in data. Concatenate successive token content values to build the assistant reply. The done event carries session metadata, including session_id when present. Send that value as the session-id header on later chat and attachment calls. The done event does not repeat the full message.

Named events:

  • token — Incremental text of the assistant reply. data is { "content": "..." }.

  • thinking — The thinking event is in preview mode - some of the features may not be fully operational yet.

    Optional reasoning text. data is { "content": "..." }. Do not treat this as part of the user-facing reply unless the client displays reasoning.

  • tool_start — The agent started a tool. data is { "tool_name": "...", "tool_call_id": "..." }.

  • tool_end — The agent finished a tool. data uses the same fields as tool_start.

  • tool_result — Tool output. data is { "tool_name": "...", "tool_call_id": "...", "output": {} }. output is a JSON object or array. Credential-like keys in output are omitted.

  • done — The stream completed. data includes agent_id, agent_type, and session_id when present. At least one of these fields is sent.

  • error — The error event is in preview mode - some of the features may not be fully operational yet.

    A failure during generation. data includes message and/or code. Example codes are AGENT_SETUP and RECURSION_LIMIT.

SSE data fields use snake_case (session_id, agent_id, agent_type). They are not the camelCase fields of the synchronous chat ChatResponse (sessionId, agentId, agentType).

HTTP 400, 401, 403, and 500 responses are JSON problem bodies, not SSE events. They occur when the request is rejected before the stream starts. Unknown event names are not forwarded. Frames without an event name and with no data may appear as keepalives; ignore them.

Required scopes
This endpoint requires the following scopes:
  • : Needed to execute agentic chat.
  • : Needed to execute agentic chat by customers.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

Header parameters
session-idstring · uuidOptional

Optional UUID of the AI Service chat session. If omitted, the system generates one.

Reuse the same value on later chat and attachment calls to continue the same session, access attachments from that session, and keep conversational memory when enabledMemory is true on the agent. A new value starts a new session.

On Starting agent chat, the value is sessionId in the JSON response. On Starting agent chat stream, the value is session_id in the SSE done event. When a chat request includes attachments, send the same value returned as sessionId from the upload or from assigning existing media. Do not send sessionId in the request body. Omitting session-id when you assign media starts a new session and returns that sessionId.

AcceptstringOptional

Use text/event-stream to receive the response as a Server-Sent Events stream.

Example: text/event-stream
Body
agentIdstringRequired

Unique identifier of the agent.

messagestringRequired

The user message to the agent.

Responses
200

Chat response stream as Server-Sent Events. Each named event carries a JSON object in data. Concatenate token content values for the assistant reply. When session_id is present on the done event, send it as the session-id header on later calls.

text/event-stream
stringOptional

Complete Server-Sent Events body. The HTTP entity is event: / data: text, not a JSON object.

Each data line is a JSON object. The object shape depends on the event name and is documented by ChatStreamEventData:

  • token — ChatStreamTokenData

  • thinking — The thinking event is in preview mode - some of the features may not be fully operational yet.

    ChatStreamThinkingData

  • tool_start and tool_end — ChatStreamToolMetaData

  • tool_result — ChatStreamToolResultData

  • done — ChatStreamDoneData

  • error — The error event is in preview mode - some of the features may not be fully operational yet.

    ChatStreamErrorData

post/ai-service/{tenant}/agentic/chat-stream
POST /ai-service/{tenant}/agentic/chat-stream HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 78

{
  "agentId": "complaint-agent",
  "message": "Find a product with \"EON1243\" code"
}
event: token
data: {"content":"Standard "}

event: token
data: {"content":"delivery is available for order EON1243."}

event: done
data: {"agent_id":"generic-agent","agent_type":"generic","session_id":"33a550d0-d812-4fb2-bb0d-d50dbfe3627b"}

Starting agent async chat

post

Allows for communication with Emporix agents in async way. Conversational continuity requires both the session-id header and enabledMemory set to true on the agent. Collaborations configured in agentCollaborations run in the same session.

When the request includes attachments, each attachments[].attachmentId must reference a file already uploaded in this session. Send the upload sessionId as the session-id header. The attachment must already be attached to the agentId in the request body. After a file upload, send that same path agentId in the chat body. After reuse, send the target agent's path agentId in the chat body. If they differ, the request returns 400. To use the file with a different agent, first assign the attachment to that agent with attachmentId on POST /ai-service/{tenant}/agentic/{agentId}/attachments using the target agentId in the path, then chat with that target agent.

Required scopes
This endpoint requires the following scopes:
  • : Needed to execute agentic chat.
  • : Needed to execute agentic chat by customers.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

Header parameters
session-idstring · uuidOptional

Optional UUID of the AI Service chat session. If omitted, the system generates one.

Reuse the same value on later chat and attachment calls to continue the same session, access attachments from that session, and keep conversational memory when enabledMemory is true on the agent. A new value starts a new session.

On Starting agent chat, the value is sessionId in the JSON response. On Starting agent chat stream, the value is session_id in the SSE done event. When a chat request includes attachments, send the same value returned as sessionId from the upload or from assigning existing media. Do not send sessionId in the request body. Omitting session-id when you assign media starts a new session and returns that sessionId.

Body
agentIdstringRequired

Unique identifier of the agent.

messagestringRequired

The user message to the agent.

Responses
201

Job ID response.

application/json
jobIdstringOptional

Identifier of the job.

post/ai-service/{tenant}/agentic/chat-async
POST /ai-service/{tenant}/agentic/chat-async HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 78

{
  "agentId": "complaint-agent",
  "message": "Find a product with \"EON1243\" code"
}
{
  "jobId": "68835cc3ef4e8e1425c360ad"
}

Uploading attachment

post

Uploads a new file and assigns it to the agent, or assigns an existing media asset to the agent.

Send exactly one of attachment or attachmentId. Sending both or neither returns 400.

Upload a file: Send the attachment form field. The response is 201 with the new attachment id and sessionId. Supported file extensions:

  • jpg

  • jpeg

  • png

  • pdf

  • csv

  • text

  • txt

Assign existing media: Send attachmentId and the target agent's agentId in the path. Use either the attachmentId form field or an application/json body with attachmentId. The response is 200 with the attachment id and sessionId. If you omit the session-id header, the response includes the generated sessionId.

With the ai.agentexecution_manage scope, attachmentId can be any existing media asset. The asset does not have to belong to the session and does not have to already have references. AI Service adds an AGENT reference and attaches the file to the session in the response.

With only the ai.agentexecution_manage_own scope, the attachment must already belong to the session-id session.

Chat with the attachment: Call the Starting agent chat, Starting agent chat stream, or Starting agent async chat endpoint. Send the returned sessionId as the session-id header and the path agentId in the chat body. If the chat agentId is not the agent in this path, the API returns 400 with the message Agent chat attachment with id={attachmentId} cannot be used to chat with agentId={agentId}.

Required scopes
This endpoint requires the following scopes:
  • : Needed to execute agentic chat.
  • : Needed to execute agentic chat by customers.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

agentIdstringRequired

Unique identifier of the agent that receives the attachment. For a file upload, a later chat request must send this same value in the body agentId field. When you reuse an attachment, this path value is the target agent. The later chat request must send that target agentId.

Header parameters
session-idstring · uuidOptional

Optional UUID of the AI Service chat session. If omitted, the system generates one.

Reuse the same value on later chat and attachment calls to continue the same session, access attachments from that session, and keep conversational memory when enabledMemory is true on the agent. A new value starts a new session.

On Starting agent chat, the value is sessionId in the JSON response. On Starting agent chat stream, the value is session_id in the SSE done event. When a chat request includes attachments, send the same value returned as sessionId from the upload or from assigning existing media. Do not send sessionId in the request body. Omitting session-id when you assign media starts a new session and returns that sessionId.

Body
or
Responses
200

Existing media assigned to the agent. The body contains the attachment id and the sessionId to send on later chat requests.

application/json
idstringOptional

Unique identifier of the created attachment.

sessionIdstringOptional

Unique identifier of the session the attachment is on. Send this value as the session-id header on later chat requests. If the assign request omits session-id, this value is the generated session.

post/ai-service/{tenant}/agentic/{agentId}/attachments
POST /ai-service/{tenant}/agentic/{agentId}/attachments HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 23

{
  "attachment": "binary"
}
{
  "id": "68835cc3ef4e8e1425c360ad",
  "sessionId": "0499bef6-a4d2-45b9-86a0-2edf7d70d726"
}
PreviousAgent
NextAgent Logs

Last updated

Was this helpful?