> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/api-documentation/api-guides/artificial-intelligence/ai-service/api-reference/agent-chat.md).

# Agent Chat

Chat With Agents

## Starting agent chat

> 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.\
> \
> Generated replies include provenance details in \`mixins\` and the corresponding schema reference in \`metadata\`.\
> \
> When the agent generates an image or a file, \`artifacts\` lists that file. Download a ready file with \`artifactId\`.

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent Chat","description":"Chat With Agents"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agentexecution_manage_own","ai.agentexecution_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"ai.text_manage":"Needed to execute actions related to the text generation.","ai.completion_manage":"Needed to execute actions related to the AI completions.","ai.agentexecution_manage":"Needed to execute agentic chat.","ai.agentexecution_manage_own":"Needed to execute agentic chat by customers.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"schemas":{"ChatResponse":{"type":"object","properties":{"agentId":{"type":"string","description":"Unique identifier of the agent."},"agentType":{"$ref":"#/components/schemas/AgentType"},"sessionId":{"type":"string","description":"Unique identifier of the session. Send this value back as the `session-id` header on later chat and attachment calls."},"message":{"type":"string","description":"Agent message."},"artifacts":{"type":"array","description":"Generated images and files. Omitted when the reply has none.","items":{"$ref":"#/components/schemas/ChatArtifact"}},"mixins":{"$ref":"#/components/schemas/ProvenanceMixins"},"metadata":{"$ref":"#/components/schemas/ProvenanceMetadata"}}},"AgentType":{"type":"string","description":"Type of the agent handling the request.","enum":["generic","complaint","anti_fraud"]},"ChatArtifact":{"description":"Metadata for one generated image or file.","oneOf":[{"$ref":"#/components/schemas/ChatArtifactReady"},{"$ref":"#/components/schemas/ChatArtifactFailed"}]},"ChatArtifactReady":{"type":"object","description":"A generated file whose bytes are stored. `artifactId` is present.","required":["artifactId","kind","filename","mimeType","size","status"],"properties":{"artifactId":{"type":"string","description":"Media asset id."},"kind":{"type":"string","enum":["image","file"],"description":"Generated content type."},"filename":{"type":"string","description":"File name."},"mimeType":{"type":"string","description":"Media type of the file."},"size":{"type":"integer","description":"Size in bytes."},"status":{"type":"string","enum":["ready"],"description":"`ready`."},"generationId":{"type":"string","description":"Generation identifier."}}},"ChatArtifactFailed":{"type":"object","description":"A generated file that was not stored.","required":["kind","filename","mimeType","size","status"],"properties":{"kind":{"type":"string","enum":["image","file"],"description":"Generated content type."},"filename":{"type":"string","description":"File name."},"mimeType":{"type":"string","description":"Media type of the file."},"size":{"type":"integer","description":"Size in bytes."},"status":{"type":"string","enum":["failed"],"description":"`failed`."},"errorCode":{"type":"string","description":"Failure code."},"generationId":{"type":"string","description":"Generation identifier."}}},"ProvenanceMixins":{"type":"object","description":"Provenance details for generated content. Entries are `mixins.provenance.entries`.\nClients that display generated content to a person must disclose that the content is AI-generated.","required":["provenance"],"properties":{"provenance":{"type":"object","required":["entries"],"properties":{"entries":{"type":"array","minItems":1,"items":{"type":"object","required":["origin","contentVersion","generationId","generatedAt","generator","reviewStatus"],"properties":{"origin":{"type":"string","enum":["ai_generated"],"description":"Source of the content. `ai_generated` means the content was produced by AI."},"contentVersion":{"type":"integer","description":"Version of the generated content."},"generationId":{"type":"string","description":"Unique identifier of the generation."},"generatedAt":{"type":"string","format":"date-time","description":"Date and time when the content was generated. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-30T13:18:02.379Z`"},"generator":{"type":"string","description":"Identifier of the generator."},"generatorVersion":{"type":"integer","description":"Version of the generator, when available."},"model":{"type":"string","description":"AI model used to generate the content, when available."},"reviewStatus":{"type":"string","description":"Review state of the generated content. A generation response uses `not_reviewed`.\nAn entry stored when a person saves applied AI content uses `reviewed`."},"aiGeneratedFields":{"type":"array","items":{"type":"string"},"description":"Entity fields this generation wrote. Generation responses omit it.\nA client records it when the person applies the generation."}}}}}}}},"ProvenanceMetadata":{"type":"object","description":"Schema references for response mixins.","properties":{"mixins":{"type":"object","additionalProperties":{"type":"string"}}}},"ErrorMessage":{"type":"object","properties":{"code":{"type":"integer"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}},"description":""},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}},"AgenticRequest":{"type":"object","properties":{"agentId":{"type":"string","description":"Unique identifier of the agent."},"message":{"type":"string","description":"The user message to the agent."},"attachments":{"type":"array","items":{"type":"object","properties":{"attachmentId":{"type":"string","description":"Identifier returned by the upload. Required for each attached file. The attachment must belong to the current session and be attached to this request's `agentId`."},"caption":{"type":"string","description":"Caption of the attachment."},"purpose":{"type":"string","description":"Purpose of the attachment."}},"required":["attachmentId"]}}},"required":["agentId","message"]}},"responses":{"400_resp_common":{"description":"The request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"403_resp_common":{"description":"Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"500_resp_common":{"description":"A server-side error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"requestBodies":{"AgenticChat":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticRequest"}}}}}},"paths":{"/ai-service/{tenant}/agentic/chat":{"post":{"summary":"Starting agent chat","operationId":"POST-ai-agents-chat","responses":{"200":{"description":"Chat response.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ChatResponse"}}}}},"400":{"$ref":"#/components/responses/400_resp_common"},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"},"500":{"$ref":"#/components/responses/500_resp_common"}},"description":"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.\n\nWhen 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.\n\nGenerated replies include provenance details in `mixins` and the corresponding schema reference in `metadata`.\n\nWhen the agent generates an image or a file, `artifacts` lists that file. Download a ready file with `artifactId`.","requestBody":{"$ref":"#/components/requestBodies/AgenticChat"},"tags":["Agent Chat"]}}}}
```

## Starting agent chat stream

> 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 and provenance details for generated output. Send \`session\_id\`, when present, 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.\
> \
> &#x20; 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.\
> \* \`artifact\` — \*\*The \`artifact\` event is in preview mode\*\* - some of the features may not be fully operational yet.\
> \
> &#x20; One generated image or file. \`data\` is \`ChatStreamArtifactData\`.\
> \* \`done\` — The stream completed. \`data\` includes \`agent\_id\`, \`agent\_type\`, and \`session\_id\` when present, plus provenance details for generated output. At least one identity field is sent.\
> \* \`error\` — \*\*The \`error\` event is in preview mode\*\* - some of the features may not be fully operational yet.\
> \
> &#x20; A failure during generation. \`data\` includes \`message\` and/or \`code\`. Example codes are \`AGENT\_SETUP\` and \`RECURSION\_LIMIT\`.\
> \
> 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.

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent Chat","description":"Chat With Agents"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agentexecution_manage_own","ai.agentexecution_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"ai.text_manage":"Needed to execute actions related to the text generation.","ai.completion_manage":"Needed to execute actions related to the AI completions.","ai.agentexecution_manage":"Needed to execute agentic chat.","ai.agentexecution_manage_own":"Needed to execute agentic chat by customers.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"responses":{"400_resp_common":{"description":"The request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"403_resp_common":{"description":"Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"500_resp_common":{"description":"A server-side error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"schemas":{"ErrorMessage":{"type":"object","properties":{"code":{"type":"integer"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}},"description":""},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}},"AgenticRequest":{"type":"object","properties":{"agentId":{"type":"string","description":"Unique identifier of the agent."},"message":{"type":"string","description":"The user message to the agent."},"attachments":{"type":"array","items":{"type":"object","properties":{"attachmentId":{"type":"string","description":"Identifier returned by the upload. Required for each attached file. The attachment must belong to the current session and be attached to this request's `agentId`."},"caption":{"type":"string","description":"Caption of the attachment."},"purpose":{"type":"string","description":"Purpose of the attachment."}},"required":["attachmentId"]}}},"required":["agentId","message"]}},"requestBodies":{"AgenticChat":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticRequest"}}}}}},"paths":{"/ai-service/{tenant}/agentic/chat-stream":{"post":{"summary":"Starting agent chat stream","operationId":"POST-ai-agents-chat-stream","responses":{"200":{"description":"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.","content":{"text/event-stream":{"schema":{"type":"string","description":"Complete Server-Sent Events body. The HTTP entity is `event:` / `data:` text, not a JSON object.\n\nEach `data` line is a JSON object. The object shape depends on the event name and is documented by `ChatStreamEventData`:\n\n* `token` — `ChatStreamTokenData`\n* `thinking` — **The `thinking` event is in preview mode** - some of the features may not be fully operational yet.\n\n  `ChatStreamThinkingData`\n* `tool_start` and `tool_end` — `ChatStreamToolMetaData`\n* `tool_result` — `ChatStreamToolResultData`\n* `artifact` — **The `artifact` event is in preview mode** - some of the features may not be fully operational yet.\n\n  `ChatStreamArtifactData`\n* `done` — `ChatStreamDoneData`\n* `error` — **The `error` event is in preview mode** - some of the features may not be fully operational yet.\n\n  `ChatStreamErrorData`"}}}},"400":{"$ref":"#/components/responses/400_resp_common"},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"},"500":{"$ref":"#/components/responses/500_resp_common"}},"description":"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.\n\nWhen 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.\n\nThe 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 and provenance details for generated output. Send `session_id`, when present, as the `session-id` header on later chat and attachment calls. The `done` event does not repeat the full message.\n\nNamed events:\n\n* `token` — Incremental text of the assistant reply. `data` is `{ \"content\": \"...\" }`.\n* `thinking` — **The `thinking` event is in preview mode** - some of the features may not be fully operational yet.\n\n  Optional reasoning text. `data` is `{ \"content\": \"...\" }`. Do not treat this as part of the user-facing reply unless the client displays reasoning.\n* `tool_start` — The agent started a tool. `data` is `{ \"tool_name\": \"...\", \"tool_call_id\": \"...\" }`.\n* `tool_end` — The agent finished a tool. `data` uses the same fields as `tool_start`.\n* `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.\n* `artifact` — **The `artifact` event is in preview mode** - some of the features may not be fully operational yet.\n\n  One generated image or file. `data` is `ChatStreamArtifactData`.\n* `done` — The stream completed. `data` includes `agent_id`, `agent_type`, and `session_id` when present, plus provenance details for generated output. At least one identity field is sent.\n* `error` — **The `error` event is in preview mode** - some of the features may not be fully operational yet.\n\n  A failure during generation. `data` includes `message` and/or `code`. Example codes are `AGENT_SETUP` and `RECURSION_LIMIT`.\n\nHTTP `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.","requestBody":{"$ref":"#/components/requestBodies/AgenticChat"},"tags":["Agent Chat"]}}}}
```

## Starting agent async chat

> 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.

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent Chat","description":"Chat With Agents"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agentexecution_manage_own","ai.agentexecution_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"ai.text_manage":"Needed to execute actions related to the text generation.","ai.completion_manage":"Needed to execute actions related to the AI completions.","ai.agentexecution_manage":"Needed to execute agentic chat.","ai.agentexecution_manage_own":"Needed to execute agentic chat by customers.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"schemas":{"JobIdResponse":{"type":"object","properties":{"jobId":{"type":"string","description":"Identifier of the job."}}},"ErrorMessage":{"type":"object","properties":{"code":{"type":"integer"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}},"description":""},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}},"AgenticRequest":{"type":"object","properties":{"agentId":{"type":"string","description":"Unique identifier of the agent."},"message":{"type":"string","description":"The user message to the agent."},"attachments":{"type":"array","items":{"type":"object","properties":{"attachmentId":{"type":"string","description":"Identifier returned by the upload. Required for each attached file. The attachment must belong to the current session and be attached to this request's `agentId`."},"caption":{"type":"string","description":"Caption of the attachment."},"purpose":{"type":"string","description":"Purpose of the attachment."}},"required":["attachmentId"]}}},"required":["agentId","message"]}},"responses":{"400_resp_common":{"description":"The request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"403_resp_common":{"description":"Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"500_resp_common":{"description":"A server-side error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"requestBodies":{"AgenticChat":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticRequest"}}}}}},"paths":{"/ai-service/{tenant}/agentic/chat-async":{"post":{"summary":"Starting agent async chat","operationId":"POST-ai-agents-chat-async","responses":{"201":{"description":"Job ID response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobIdResponse"}}}},"400":{"$ref":"#/components/responses/400_resp_common"},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"},"500":{"$ref":"#/components/responses/500_resp_common"}},"description":"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.\n\nWhen 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.","requestBody":{"$ref":"#/components/requestBodies/AgenticChat"},"tags":["Agent Chat"]}}}}
```

## Uploading attachment

> 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\`. The following file extensions and content types are supported:\
> &#x20; \- jpg, jpeg – \`image/jpeg\`\
> &#x20; \- png – \`image/png\`\
> &#x20; \- pdf – \`application/pdf\`\
> &#x20; \- csv – \`text/csv\`\
> &#x20; \- text, txt – \`text/plain\`\
> &#x20; \- json – \`application/json\`\
> &#x20; \- xml – \`application/xml\` or \`text/xml\`\
> &#x20; \- html, htm – \`text/html\`\
> &#x20; \- xlsx – \`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\`\
> \
> The file extension must match the content type of the \`attachment\` part. Content type parameters, such as \`charset=utf-8\`, are ignored. Legacy Excel files (\`xls\`) are not supported. An unsupported content type or file extension returns \`400\`, and the error message lists the supported file extensions.\
> \
> \*\*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}\`.

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent Chat","description":"Chat With Agents"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agentexecution_manage_own","ai.agentexecution_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"ai.text_manage":"Needed to execute actions related to the text generation.","ai.completion_manage":"Needed to execute actions related to the AI completions.","ai.agentexecution_manage":"Needed to execute agentic chat.","ai.agentexecution_manage_own":"Needed to execute agentic chat by customers.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"schemas":{"AttachmentResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the created attachment."},"sessionId":{"type":"string","description":"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."}}},"ErrorMessage":{"type":"object","properties":{"code":{"type":"integer"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}},"description":""},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}},"responses":{"400_resp_common":{"description":"The request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"403_resp_common":{"description":"Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"500_resp_common":{"description":"A server-side error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}},"paths":{"/ai-service/{tenant}/agentic/{agentId}/attachments":{"post":{"summary":"Uploading attachment","operationId":"POST-ai-agents-upload-attachment","responses":{"200":{"description":"Existing media assigned to the agent. The body contains the attachment `id` and the `sessionId` to send on later chat requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentResponse"}}}},"201":{"description":"Attachment created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentResponse"}}}},"400":{"$ref":"#/components/responses/400_resp_common"},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"},"500":{"$ref":"#/components/responses/500_resp_common"}},"description":"Uploads a new file and assigns it to the agent, or assigns an existing media asset to the agent.\n\nSend exactly one of `attachment` or `attachmentId`. Sending both or neither returns `400`.\n\n**Upload a file:** Send the `attachment` form field. The response is `201` with the new attachment `id` and `sessionId`. The following file extensions and content types are supported:\n  - jpg, jpeg – `image/jpeg`\n  - png – `image/png`\n  - pdf – `application/pdf`\n  - csv – `text/csv`\n  - text, txt – `text/plain`\n  - json – `application/json`\n  - xml – `application/xml` or `text/xml`\n  - html, htm – `text/html`\n  - xlsx – `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`\n\nThe file extension must match the content type of the `attachment` part. Content type parameters, such as `charset=utf-8`, are ignored. Legacy Excel files (`xls`) are not supported. An unsupported content type or file extension returns `400`, and the error message lists the supported file extensions.\n\n**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`.\n\nWith 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.\n\nWith only the `ai.agentexecution_manage_own` scope, the attachment must already belong to the `session-id` session.\n\n**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}`.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"oneOf":[{"type":"object","required":["attachment"],"additionalProperties":false,"properties":{"attachment":{"type":"string","format":"binary","description":"Content of the file. Use this field to upload a new file."}}},{"type":"object","required":["attachmentId"],"additionalProperties":false,"properties":{"attachmentId":{"type":"string","description":"Identifier of an existing media asset. With `ai.agentexecution_manage`, any media id can be assigned to the path agent. With only `ai.agentexecution_manage_own`, the attachment must already belong to the session."}}}]}},"application/json":{"schema":{"type":"object","required":["attachmentId"],"additionalProperties":false,"properties":{"attachmentId":{"type":"string","description":"Identifier of an existing media asset. With `ai.agentexecution_manage`, any media id can be assigned to the path agent. With only `ai.agentexecution_manage_own`, the attachment must already belong to the session."}}}}}},"tags":["Agent Chat"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.emporix.io/api-documentation/api-guides/artificial-intelligence/ai-service/api-reference/agent-chat.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
