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

AI Tutorial

With Emporix support for AI, you can enhance text for product descriptions and generate AI completions.

Before you start

Make sure to configure your API token. To do that, you can use the Configuration Service and store the token under openAiApiToken key.

Send the request to the Creating Configurations endpoint.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference
curl -L \
  --request POST \
  --url 'https://api.emporix.io/configuration/{tenant}/configurations' \
  --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "_id": "openAiApiToken",
      "value": "mc-ZtG7zOY9lywNv2539383fLeJr34444",
      "version": 1,
      "secured": false
    }
]

How to generate an AI supported text for a product

You can generate the text by sending a request based on a provided prompt. To send the request, use the Text Generation endpoint.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

How to generate an AI completion

Completion is generated based on chat history. It's a generated response or continuation of a conversation, crafted by the AI to address the given input in context. It can include answering questions, providing suggestions, or completing a sentence or thought. The currently supported AI engine for the completion is OpenAI. To generate the AI completion, send the request using the AI Completions endpoint.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

How to create an AI agent using a template

Create an AI agent using one of Emporix agent template.

Get the agent template ID

To create an agent, you'll need a template ID.

Copy and note down the template ID of your interest.

Create an agent

Call the Creating agent instance based on the template endpoint to add an agent to your system. In the path parameter, provide the templateID you have copied.

How to search for the AI Agents

When you want to add a trigger for an enabled AI agent through API, for example as a part of a digital process or from an external system, you need to fetch the specific agent details.

  • Use the Searching agents endpoint to pass a query parameter against the agents in your system.

For example, to find agents of Complaint type:

You can use the retrieved details to establish the required connections and triggers for the AI Agent.

How to create an MCP server and attach it to an agent

You can manage two types of tenant MCP servers through the API:

  • Custom (type: custom) – points to your own MCP implementation with a URL and transport. Use this to connect agents to an external system, such as an ERP.

  • Dynamic (type: dynamic) – defines tools inline. Each tool invokes an Emporix Cloud Function (config.invocation.functionId).

The workflow is the same for both types: create the server, attach it to an agent, then verify. The examples below show requests for custom and dynamic MCP management.

Emporix also provides predefined domain MCP servers (type: predefined) that you can attach to an agent. These domain MCP servers cannot be created through the API.

Dynamic MCP servers This functionality is in preview mode - some of the features may not be fully operational yet.

Hosting of Cloud Functions and the use of dynamic MCP servers are not included in standard billing plans and are billed separately on a pay-as-you-go basis. If you're interested in getting access to these features, contact the Sales Team.

For more details, see Hosting and Extension and Cloud Function Hosting.

To follow this workflow:

  • The OAuth2 access token must include the ai.agent_manage scope to create and attach the server, and ai.agent_read to retrieve the results.

  • For a custom MCP server, you need a reachable MCP endpoint. Use streamable_http as the transport type. If the server requires authorization, create an AI token first with the Upserting token endpoint and pass its ID as config.authorizationHeaderToken.id.

  • For a dynamic MCP server, a Cloud Function must already exist on the tenant. See Extension and Cloud Function Hosting and Hosting in the Management Dashboard. Use that function's ID as functionId. When the server is enabled, the API validates each functionId. The request returns 400 if a referenced function does not exist on the tenant.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference
1

Create the MCP server

Call the Upserting MCP server endpoint. The request replaces all existing data for that server ID. A successful create returns 201 with the server ID. A successful update returns 204.

Set the type to custom (if omitted, it defaults to custom). Provide the values for name, transport, and config.url. The config.authorizationHeaderName and config.authorizationHeaderToken fields are optional. The created MCP server stays disabled at first (enabled defaults to false if omitted). To enable it, set enabled to true.

Set the type to dynamic and provide the inline tools. The created MCP server stays disabled at first (enabled defaults to false if omitted). To enable it, set enabled to true.

Each tool needs a unique name that contains only letters, numbers, and underscores, a prompt that tells the agent when to call it, and a config with:

  • inputSchema – a JSON Schema document provided as a JSON string

  • invocation.functionId and invocation.method – the Cloud Function to call and the HTTP method

  • invocation.argsLocation – query or body; defaults to body when omitted

  • requiredScopes – optional OAuth scopes required to invoke the tool (see Cloud Function identity headers)

Each tool also stays disabled at first (enabled defaults to false if omitted). To enable a tool so the agent can call it, set enabled to true.

2

Attach the server to an agent

Call the Partially updating agent endpoint to add the MCP server to an existing agent, for example an agent you created from a template. A successful request returns 204.

Use the same endpoint if you want to attach Emporix domain MCP servers (type: predefined) to an AI agent.

Set type to custom and pass the managed server ID in mcpServer.id.

Set type to dynamic and pass the managed server ID in mcpServer.id. The tools array on the attachment is an optional allowlist of tool names from the dynamic MCP server. Omit tools to grant the agent all enabled tools on that server.

Set the type to predefined and pass the Emporix domain. The tools array lists the tools from that domain MCP server that the agent uses.

The available domain values are customer, extensibility, order, product, or frontend.

If you replace the whole mcpServers array (op: REPLACE on /mcpServers), include any existing predefined, custom, or dynamic attachments you still need.

You can also attach servers with the Upserting agent endpoint. That PUT replaces the whole agent document. The body must include all required agent fields, including userPrompt, triggers, llmConfig, and mcpServers.

3

Verify the attachment

Call the Retrieving agent by ID endpoint with expand=mcpServers to return the full mcpServer object for custom and dynamic attachments. Without expand, mcpServer typically contains only the id.

Listing and searching agents return the same mcpServers attachments, including predefined, and also support expand=mcpServers.

To inspect the server itself, call the Retrieving MCP server by ID endpoint:

The response includes the inline tools.

4

Update the MCP server

Call the Partially updating MCP server endpoint. A successful request returns 204.

For example, replace the server name:

You can also replace config.url in the same way.

For example, replace the tool list:

To set enabled to false when an enabled agent uses this MCP server, send force=true as a query parameter. The API then disables both the agent and the MCP server.

Cloud Function identity headers

When a tool on a dynamic MCP server runs, Emporix injects identity headers into the Cloud Function so the function can call Emporix APIs without embedding credentials.

Emporix sets these headers on the function request:

  • emporix-token – Token used to call Emporix APIs. It is the HTTP caller's token, a token obtained from the commerce event trigger's eventScopes, or the token used by an external MCP client.

  • emporix-tenant – Always set. Identifies the tenant that invoked the function.

  • emporix-scopes – Scopes assigned to that token. Use it to see which resources the function can access.

  • emporix-user-id – Set for employee tokens on HTTP agent calls and for customer tokens. Not set for service tokens, commerce events, or external MCP clients.

  • emporix-session-id – Set when the tool runs inside an agent session.

  • emporix-legal-entity-id – Set only for customer tokens when the customer is assigned to a legal entity. Not set for service tokens, commerce events, or external MCP clients.

For the full header table, see Invoking cloud functions. For how these headers are set in the Management Dashboard, see Cloud Function context for dynamic MCP tools.

How to set event scopes for a commerce event trigger

When a commerce event triggers an agent, for example product.product-created, there is no caller token to pass to a Cloud Function on a dynamic MCP server. Set eventScopes on the commerce_events trigger so AI Service can obtain an Emporix token with those IAM scopes and forward it as emporix-token.

  • If you omit eventScopes or leave it empty, the Cloud Function receives no emporix-token.

  • Each listed scope must be a scope the caller is allowed to grant.

The eventScopes field is not the same as requiredScopes. On the agent, requiredScopes controls who may trigger the agent. On a dynamic MCP tool, requiredScopes controls who may invoke the tool.

The OAuth2 access token must include the ai.agent_manage scope.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

Call the Partially updating agent endpoint to add a commerce event trigger with eventScopes. A successful request returns 204.

If the agent already has a commerce_events trigger, replace the triggers array and keep any other trigger types you still need, for example endpoint. You can also set eventScopes when you create or replace the whole agent with the Upserting agent endpoint. That PUT replaces the whole agent document.

How to communicate with an Agent

For some Agents, it is convenient to trigger their actions by API calls. To allow communication with the selected agent, you can use the dedicated endpoints. If the agent has a custom, dynamic, or predefined MCP server attached, it can invoke those tools during the chat without extra fields in the request body.

When the agent invokes a dynamic MCP tool during chat, Emporix forwards the caller's identity to the Cloud Function:

  • emporix-token – Token used to call the chat endpoint. The function has the same access as the agent's caller.

  • emporix-scopes – Always populated.

  • emporix-user-id – Set for employee tokens and for customer tokens.

  • emporix-legal-entity-id – Set for customer tokens when the customer is assigned to a legal entity.

  • emporix-session-id – Set when the chat runs in a session.

See Cloud Function identity headers.

Choose the chat endpoint based on how you want to receive the agent's response:

  • Starting agent chat – when you need a single complete JSON response right away.

  • Starting agent chat stream – when you build interactive experiences, such as chat UIs, storefront assistants, or backoffice tools, that display the agent's reply as it is written and benefit from improved responsiveness.

  • Starting agent async chat – when the agent may take longer to process data or wait for another task, and you want to poll the result using the jobId.

  • When instant responses are required from the agent, send the request to the Starting agent chat

    Trigger the specific agent providing its agentId. In the message, type in your query or data you want the agent to process.

    In the above example, the German Translation Agent is triggered. The Agent acts according to its defined prompt - here, the agent is programmed to find the product name and description in the request message and translate the fields into German language. As a result, the Agent gets back with the following response:

    Save sessionId and send it as the session-id header when you need conversational continuity. See How to reuse session memory in agent chat.

  • When you want progressive output as the agent's response is generated, stream the request to the Starting agent chat stream endpoint.

    The request body uses the same agentId and message fields as the synchronous chat request. The endpoint returns the response as a Server-Sent Events stream (text/event-stream). Each frame has an event name and a JSON object in data. Concatenate successive token content values to build the assistant reply. When present, save session_id from the done event and send it as the session-id header on later turns. See How to reuse session memory in agent chat.

    The thinking and error events are in preview mode - some of the features may not be fully operational yet.

    Example stream:

    In this example, the user-facing reply is Standard delivery is available for order EON1243. The thinking event is optional reasoning and is not part of that reply unless the client displays it. An in-stream failure arrives as event: error with message and/or code in data, for example {"code":"AGENT_SETUP","message":"Agent setup failed"}. HTTP 400, 401, 403, and 500 remain JSON problem bodies when the request is rejected before the stream starts.

    Continue the same session on a later streaming turn:

    For the full event list and JSON data schemas, see Starting agent chat stream.

  • When it is more pragmatic to wait for the agent's response, for example, when the agent needs to process more data which takes more time, or the agent needs to wait for another task to be completed, use the asynchronous communication. Send the request to the agent using the Starting agent async chat.

    Similarly, provide the relevant agentId and pass your query in the message.

    In async requests, the response contains the jobId parameter, for example:

    Use the jobId to check details of the job through the Retrieving agent job by its ID endpoint. For example:

    The job entity contains information about the request and response from the agent.

How to reuse session memory in agent chat

Session memory keeps conversational data across chat turns within one session-id. Memory is opt-in per agent. Reusing the session-id header without enabling memory continues the session identity but does not store chat memory.

The OAuth2 access token must include ai.agent_manage to set enabledMemory on the agent. Chat endpoints require ai.agentexecution_manage_own for customer callers, or ai.agentexecution_manage for employee and integration callers. Retrieving a session by ID requires ai.agent_read.

To test the endpoint, open the API reference or check the example of a curl request.

1

Enable memory on the agent

Set enabledMemory to true on the agent. The default is false. You can set the flag when you create or replace the agent with the Upserting agent endpoint, or update an existing agent with the Partially updating agent endpoint.

A successful request returns 204. To keep conversational memory for collaborations, repeat this for every collaboration target.

2

Reuse the session-id header

Call a chat endpoint, for example Starting agent chat. Save sessionId from the JSON response. On Starting agent chat stream, save session_id from the SSE done event. On later turns, send that value as the session-id header.

The Starting agent chat stream and Starting agent async chat endpoints use the same header.

If you omit session-id on a follow-up call, the API starts a new session.

3

Keep collaborations in the same session

If the agent lists agentCollaborations, those collaborations stay in the caller's session. To keep conversational memory across those agents, it is recommended to set the flag to true on the calling agent (the supervisor) and each collaboration target. Listing an agent in agentCollaborations does not enable memory for it.

When enabledMemory is false, the supervisor has no stored conversation history to pass to a hand-off agent. State in the supervisor userPrompt the exact information to forward, such as an order ID, customer number, or complaint details. Incomplete or ambiguous instructions result in extra collaboration cycles between the supervisor and the called agent until the required context is available.

To inspect which agents participated, call the Retrieving agent session by ID endpoint.

A successful response includes agents, the list of agent IDs that participated in the session. For the supervisor collaboration model, see Agents collaboration.

This session-id is the AI Service conversation key. It is not the Session Context session-id or the cart session-id. The same value also scopes attachments and is forwarded as emporix-session-id when a tool runs inside an agent session. See How to pass a media file for the agents to process.

How to pass a media file for the agents to process

Agents are able to retrieve data from media attachments and use that data to execute some steps or pass it over to other agents to process. You can attach media files and then use them in the agent chat.

The following MIME types are supported:

  • image/jpeg

  • image/png

  • application/pdf

  • text/csv

  • text/plain

Media file size can be up to 10 MB.

The later chat request must send the same sessionId as the upload. The chat agentId must be an agent that already has the attachment assigned:

  • agentId – The path parameter of Uploading attachment must match agentId in the chat request body. After reuse, match the target agent instead.

  • sessionId – Send the upload response value as the session-id header on the chat request.

This pairing applies to Starting agent chat, Starting agent chat stream, and Starting agent async chat.

To use the file with a different agent, first assign the attachment to that agent. See Reuse an attachment with another agent.

1

Upload a file to an agent

To upload a file to an agent, use the dedicated Uploading attachment endpoint. The agentId in the path assigns the file to that agent.

The successful response returns an attachment id and a sessionId that scopes the upload to your chat session. Save both values. You need them when you call agent chat in the next step. Use the same {agentId} in the chat body. The same session-id is required for attachments and for session memory. See How to reuse session memory in agent chat.

How the sessionId in the response is set:

  • If you send a session-id header on the upload request (optional), the response returns the exact same value.

  • If you omit the header, the API generates a new sessionId for you.

Example response:

Attaching a media file of an unsupported type results in the 400 error, for example:

2

Refer to the attachment in agent chat

The file is assigned to the agent. In the chat request, reference it and add any extra instructions. Call the agent, for example with the Starting agent chat endpoint. Include the upload id as attachments[].attachmentId in the request body. Send the same session-id header and the same agentId as the upload path:

The agent can now process the data according to its rules and code of conduct.

If the chat agentId does not match the agent that received the upload, the request returns 400:

3

Reuse an attachment with another agent

To assign existing media to an agent, call Uploading attachment with attachmentId instead of a file. Put the target agent's agentId in the path. Send attachmentId in an application/json body. The attachmentId form field is also supported. The response is 200 with the attachment id and sessionId. If you omit the session-id header, save the sessionId from the response for later chat requests.

With the ai.agentexecution_manage scope, attachmentId can be any existing media asset. The asset does not have to belong to the session. With only the ai.agentexecution_manage_own scope, the attachment must already belong to the session-id session.

AI Service adds an AGENT reference on the media asset. After this call, chat with the new agentId, the returned sessionId as the session-id header, and the same attachments[].attachmentId.

How to export and import AI agents

Exporting AI agents lets you migrate your agents configuration together with their dependent tools and MCP servers.

You can use the export and import to:

  • Back up agents for disaster recovery

  • Migrate agents from development to production

  • Share agents across different tenants

  • Clone agents for testing

1

Export agents

Collect the agentIds you want to export, then call the Exporting agents endpoint.

The response contains:

  • data: a Base64-encoded JSON payload with the exported agents, tools, and MCP servers.

  • checksum: a hash of the decoded data string.

  • jobId: the export job identifier (you can poll the Retrieving agent job by ID endpoint if you need job status updates).

Store both data and checksum. You will need them when importing.

2

Import agents

Use the payload obtained during export and call the Importing agents endpoint. Import requires the ai.agent_manage scope.

The response summarizes what was imported and returns a jobId.

  • If imported tools or MCP servers already exist in the target tenant, they're reused.

  • If they don't exist, new instances are created. If a token is required, they get a disabled state for your review, if no token is required, they get enabled state.

  • Imported agents are also disabled by default as a safety measure.

After importing the agent, review the entities in the response summary and check if any required API tokens or credentials need to be configured before enabling the agent.

PreviousAI Service
NextAPI Reference

Last updated

Was this helpful?