Agent
Manage Agents
Retrieves agent templates based on the provided query.
- : Needed to read AI agents.
Your Emporix tenant name.
Note: The tenant name should always be provided in lowercase.
A standard query parameter is used to search for specific values.
The number of documents to be retrieved per page.
The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.
List of properties used to sort the results, separated by colons.
Fields to be returned in the response.
Fields to be expanded in the response. It means that instead of the object IDs, the whole objects are returned in the response.
List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.
- If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.
- If the header is set to
*, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages. - If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.
Flag indicating whether the total number of retrieved results should be returned.
List of agents.
LLM Prompt which describes how agent should work in a detailed way, which tools it could use to solve problems etc; it can contain examples and step by step guidance.
The fa class of react icon.
Markers that allow you to categorize the agent.
Optional JSON Schema (provided as a JSON string) that constrains the structure of the agent's generated output. Use this when you need predictable, machine-readable output instead of free-form text.
{"type":"object","properties":{"answer":{"type":"string"}},"required":["answer"]}Indicates whether the agent is enabled.
falseDefines the maximum number of reasoning steps or internal calls an AI agent is allowed to perform during a single task. Helps prevent infinite loops or excessive resource usage.
20Example: 10Defines whether session memory is stored between different agent calls. Memory is stored only for that agent and only within one session-id. The default is false. To keep conversational memory for targets in agentCollaborations, it is recommended to set the flag to true on each target as well.
falseIdentifier of the agent.
Deprecated. Indicates whether the agent is a hand-off agent. This field is no longer used. Clients should ignore it.
Type of the agent handling the request.
Prompt which is inherited from the template (if agent is created based on the template). The prompt provided by the user is then concatenated with this prompt.
The authorization token is invalid or has expired.
Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.
GET /ai-service/{tenant}/agentic/agents HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
[
{
"id": "123",
"name": {
"en": "Complaint Agent"
},
"description": {
"en": "Complaint agent"
},
"type": "complaint",
"enabled": true,
"templatePrompt": "You are an complaint agent for checking emails and do some action.",
"userPrompt": "Use get-order tool to fetch order.",
"llmConfig": {
"model": "GPT-4.1",
"apiKey": "secureApiKey",
"provider": "openai",
"maxTokens": 100000,
"temperature": 0.2
},
"triggers": [
{
"type": "endpoint"
}
],
"maxRecursionLimit": 20,
"enabledMemory": true,
"tags": [
"productivity"
],
"icon": "fa-productivity",
"mcpServers": [
{
"domain": "order",
"type": "predefined",
"tools": [
"get-orders",
"get-order"
]
}
],
"nativeTools": [
{
"name": "slack",
"config": {
"teamId": "T0445953"
}
}
],
"metadata": {
"version": 2,
"createdAt": "2025-07-25T10:31:14.509Z",
"modifiedAt": "2025-07-26T10:31:14.509Z",
"modifiedBy": {
"type": "EXTERNAL"
}
}
}
]Searches for agents based on the provided query.
- : Needed to read AI agents.
Your Emporix tenant name.
Note: The tenant name should always be provided in lowercase.
The number of documents to be retrieved per page.
The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.
List of properties used to sort the results, separated by colons.
Fields to be returned in the response.
Fields to be expanded in the response. It means that instead of the object IDs, the whole objects are returned in the response.
List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.
- If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.
- If the header is set to
*, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages. - If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.
Flag indicating whether the total number of retrieved results should be returned.
A standard query parameter is used to search for specific values.
List of agents.
LLM Prompt which describes how agent should work in a detailed way, which tools it could use to solve problems etc; it can contain examples and step by step guidance.
The fa class of react icon.
Markers that allow you to categorize the agent.
Optional JSON Schema (provided as a JSON string) that constrains the structure of the agent's generated output. Use this when you need predictable, machine-readable output instead of free-form text.
{"type":"object","properties":{"answer":{"type":"string"}},"required":["answer"]}Indicates whether the agent is enabled.
falseDefines the maximum number of reasoning steps or internal calls an AI agent is allowed to perform during a single task. Helps prevent infinite loops or excessive resource usage.
20Example: 10Defines whether session memory is stored between different agent calls. Memory is stored only for that agent and only within one session-id. The default is false. To keep conversational memory for targets in agentCollaborations, it is recommended to set the flag to true on each target as well.
falseIdentifier of the agent.
Deprecated. Indicates whether the agent is a hand-off agent. This field is no longer used. Clients should ignore it.
Type of the agent handling the request.
Prompt which is inherited from the template (if agent is created based on the template). The prompt provided by the user is then concatenated with this prompt.
The authorization token is invalid or has expired.
Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.
POST /ai-service/{tenant}/agentic/agents/search HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 23
{
"q": "name:~Complaint"
}[
{
"id": "123",
"name": {
"en": "Complaint Agent"
},
"description": {
"en": "Complaint agent"
},
"type": "complaint",
"enabled": true,
"templatePrompt": "You are an complaint agent for checking emails and do some action.",
"userPrompt": "Use get-order tool to fetch order.",
"llmConfig": {
"model": "GPT-4.1",
"apiKey": "secureApiKey",
"provider": "openai",
"maxTokens": 100000,
"temperature": 0.2
},
"triggers": [
{
"type": "endpoint"
}
],
"maxRecursionLimit": 20,
"enabledMemory": true,
"tags": [
"productivity"
],
"icon": "fa-productivity",
"mcpServers": [
{
"domain": "order",
"type": "predefined",
"tools": [
"get-orders",
"get-order"
]
}
],
"nativeTools": [
{
"name": "slack",
"config": {
"teamId": "T0445953"
}
}
],
"metadata": {
"version": 2,
"createdAt": "2025-07-25T10:31:14.509Z",
"modifiedAt": "2025-07-26T10:31:14.509Z",
"modifiedBy": {
"type": "EXTERNAL"
}
}
}
]Retrieves the agent by given ID.
- : Needed to read AI agents.
Your Emporix tenant name.
Note: The tenant name should always be provided in lowercase.
Fields to be returned in the response.
Fields to be expanded in the response. It means that instead of the object IDs, the whole objects are returned in the response.
Returns the configuration stored for this agent version. Omit the parameter to return the live agent.
The response is 404 when the agent or this version does not exist.
Cannot be combined with allVersions query parameter.
When true, the response includes versions field containing the stored history of previous configurations.
Cannot be combined with version query parameter.
falseList of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.
- If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.
- If the header is set to
*, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages. - If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.
A single agent.
LLM Prompt which describes how agent should work in a detailed way, which tools it could use to solve problems etc; it can contain examples and step by step guidance.
The fa class of react icon.
Markers that allow you to categorize the agent.
Optional JSON Schema (provided as a JSON string) that constrains the structure of the agent's generated output. Use this when you need predictable, machine-readable output instead of free-form text.
{"type":"object","properties":{"answer":{"type":"string"}},"required":["answer"]}Indicates whether the agent is enabled.
falseDefines the maximum number of reasoning steps or internal calls an AI agent is allowed to perform during a single task. Helps prevent infinite loops or excessive resource usage.
20Example: 10Defines whether session memory is stored between different agent calls. Memory is stored only for that agent and only within one session-id. The default is false. To keep conversational memory for targets in agentCollaborations, it is recommended to set the flag to true on each target as well.
falseIdentifier of the agent.
Deprecated. Indicates whether the agent is a hand-off agent. This field is no longer used. Clients should ignore it.
Type of the agent handling the request.
Prompt which is inherited from the template (if agent is created based on the template). The prompt provided by the user is then concatenated with this prompt.
The request was syntactically incorrect.
The authorization token is invalid or has expired.
Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.
Example response
GET /ai-service/{tenant}/agentic/agents/{agentId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
{
"id": "123",
"name": {
"en": "Complaint Agent"
},
"description": {
"en": "Complaint agent"
},
"type": "complaint",
"enabled": true,
"templatePrompt": "You are an complaint agent for checking emails and do some action.",
"userPrompt": "Use get-order tool to fetch order.",
"llmConfig": {
"model": "GPT-4.1",
"apiKey": "secureApiKey",
"provider": "openai",
"maxTokens": 100000,
"temperature": 0.2
},
"triggers": [
{
"type": "endpoint"
}
],
"maxRecursionLimit": 20,
"enabledMemory": true,
"tags": [
"productivity"
],
"icon": "fa-productivity",
"mcpServers": [
{
"domain": "order",
"type": "predefined",
"tools": [
"get-orders",
"get-order"
]
}
],
"nativeTools": [
{
"name": "slack",
"config": {
"teamId": "T0445953"
}
}
],
"metadata": {
"version": 2,
"createdAt": "2025-07-25T10:31:14.509Z",
"modifiedAt": "2025-07-26T10:31:14.509Z",
"modifiedBy": {
"type": "EMPLOYEE",
"id": "jane.doe"
}
}
}Updates or creates a specified product by replacing all of its existing data with data from the request body. If the metadata.version is provided then optimistic locking is enabled and version must match the version in the database. A successful update increments metadata.version and stores the previous configuration. A request that sends a stale metadata.version returns 409.
- : Needed to manage AI agents.
Your Emporix tenant name.
Note: The tenant name should always be provided in lowercase.
List of languages in which localized fields in the request body are provided.
- If the header is set to
*, the localized fields should be provided as maps of translations, where the keys are language codes and values are the fields in their respective languages. - If the header is set to a specific language, the localized fields should be provided as strings.
- If the header is empty, the endpoint assumes that the localized fields are provided in the default language defined in the Configuration Service.
Note: You can provide the localized fields only in languages defined in the Configuration Service. In case the fields are provided in languages that are not defined in the Configuration Service, the request is rejected.
LLM Prompt which describes how agent should work in a detailed way, which tools it could use to solve problems etc; it can contain examples and step by step guidance.
The fa class of react icon.
Markers that allow you to categorize the agent.
Optional JSON Schema (provided as a JSON string) that constrains the structure of the agent's generated output. Use this when you need predictable, machine-readable output instead of free-form text.
{"type":"object","properties":{"answer":{"type":"string"}},"required":["answer"]}Indicates whether the agent is enabled.
falseDefines the maximum number of reasoning steps or internal calls an AI agent is allowed to perform during a single task. Helps prevent infinite loops or excessive resource usage.
20Example: 10Defines whether session memory is stored between different agent calls. Memory is stored only for that agent and only within one session-id. The default is false. To keep conversational memory for targets in agentCollaborations, it is recommended to set the flag to true on each target as well.
falseID of created agent.
Identifier of the resource.
The resource has been successfully updated.
The request was syntactically incorrect.
The authorization token is invalid or has expired.
Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.
Example response
There are three possible reasons:
- Resource with given code already exists, please choose unique code for your resource
- Optimistic locking failed. If user sends metadata/version attribute which is outdated (someone else updated resource in the time user was performing his changes). User should retrieve the latest product data and retry the request.
- Optimistic locking failed. User did not provide metadata/version attribute in update request, but someone else updated product while it was internally handled by product service. Resending the same request can result in successful update, but the update can override recently persisted changes.
PUT /ai-service/{tenant}/agentic/agents/{agentId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 600
{
"name": {
"en": "Complaint Agent"
},
"description": {
"en": "Complaint agent"
},
"enabled": true,
"userPrompt": "You are an complaint agent for checking emails and do some action.",
"llmConfig": {
"model": "GPT-4.1",
"token": {
"id": "openai-token"
},
"provider": "openai",
"maxTokens": 100000,
"temperature": 0.2
},
"triggers": [
{
"type": "endpoint"
}
],
"maxRecursionLimit": 20,
"enabledMemory": true,
"tags": [
"productivity"
],
"icon": "fa-productivity",
"mcpServers": [
{
"domain": "order",
"type": "predefined",
"tools": [
"get-orders",
"get-order"
]
}
],
"nativeTools": [
{
"id": "teams-tool-1",
"allowedOperations": [
"sendMessage",
"collaborateOnChannel"
]
}
]
}{
"id": "a81bc81b-dead-4e5d-abff-90865d1e13b1"
}Deletes agent by given ID.
Important: If an agent is being used by another agent as collaboration agent then delete operation is not possible without force flag set to true.
- : Needed to manage AI agents.
Your Emporix tenant name.
Note: The tenant name should always be provided in lowercase.
Allows you to remove a given entity even if it is used as a dependency in other entries. In that case, the removed entity is unassigned from other entries.
falseGiven agent has been deleted.
No content
The request was syntactically incorrect.
The authorization token is invalid or has expired.
Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.
Example response
DELETE /ai-service/{tenant}/agentic/agents/{agentId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
No content
Partially updates a single agent document with given information. Single update may contain multiple partial updates in the form of an array. It contains the allowed operations list:
add(adding an item to the items list)remove(removing an item from the items list)replace(replacing an item with given ID with new definition) A successful update incrementsmetadata.versionand stores the previous configuration. A request that sends a stalemetadata.versionreturns409.
- : Needed to manage AI agents.
Your Emporix tenant name.
Note: The tenant name should always be provided in lowercase.
Partial update operation list.
/nameValue of the string type.
Any part of the details object.
No Content
No content
The request was syntactically incorrect.
The authorization token is invalid or has expired.
Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.
Example response
There are three possible reasons:
- Resource with given code already exists, please choose unique code for your resource
- Optimistic locking failed. If user sends metadata/version attribute which is outdated (someone else updated resource in the time user was performing his changes). User should retrieve the latest product data and retry the request.
- Optimistic locking failed. User did not provide metadata/version attribute in update request, but someone else updated product while it was internally handled by product service. Resending the same request can result in successful update, but the update can override recently persisted changes.
PATCH /ai-service/{tenant}/agentic/agents/{agentId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 130
[
{
"op": "REPLACE",
"path": "/description",
"value": "New agent description"
},
{
"op": "REPLACE",
"path": "/name",
"value": "Complaint Agent"
}
]No content
Last updated
Was this helpful?