# Agent

Manage Agents

## Listing agents

> Retrieves agent templates based on the provided query.

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent","description":"Manage Agents"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agent_read"]}],"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.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"schemas":{"AgentResponse":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentRequestAndResponse"},{"type":"object","properties":{"id":{"type":"string","description":"Identifier of the agent."},"nativeTools":{"$ref":"#/components/schemas/NativeToolsResponse"},"llmConfig":{"oneOf":[{"$ref":"#/components/schemas/EmporixLlm"},{"$ref":"#/components/schemas/ApiKeyLlmResponse"},{"$ref":"#/components/schemas/SelfHostedLlmResponse"}]},"mcpServers":{"$ref":"#/components/schemas/AgentMcpServersResponse"},"handOff":{"allOf":[{"$ref":"#/components/schemas/HandOff"}]},"type":{"$ref":"#/components/schemas/AgentType"},"templatePrompt":{"type":"string","description":"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."},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"BaseForAgentRequestAndResponse":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentAndTemplate"},{"type":"object","properties":{"triggers":{"type":"array","items":{"$ref":"#/components/schemas/AgentTrigger"}},"agentCollaborations":{"$ref":"#/components/schemas/AgentCollaborations"},"maxRecursionLimit":{"type":"integer","description":"Defines 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.","default":20,"minimum":1,"maximum":50},"enabledMemory":{"type":"boolean","description":"Defines whether the session memory should be stored between different agent calls.","default":false}},"required":["userPrompt","triggers"]}]},"BaseForAgentAndTemplate":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentAndTemplateAndHandOff"},{"type":"object","properties":{"userPrompt":{"type":"string","description":"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."},"icon":{"type":"string","description":"The fa class of react icon."},"tags":{"type":"array","items":{"type":"string","description":"Markers that allow you to categorize the agent."}},"enabled":{"type":"boolean","description":"Indicates whether the agent is enabled.","default":false}},"required":["name"]}]},"BaseForAgentAndTemplateAndHandOff":{"type":"object","properties":{"name":{"type":"object","description":"Localized name of the agent.","additionalProperties":{"type":"string"}},"description":{"type":"object","description":"Description of the agent.","additionalProperties":{"type":"string"}}}},"AgentTrigger":{"oneOf":[{"type":"object","properties":{"type":{"$ref":"#/components/schemas/TriggerType"}},"required":["type"]},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/CommerceEventsTriggerType"},"config":{"type":"object","description":"Additional configuration for the trigger.","properties":{"events":{"type":"string","description":"List of events that trigger the agent."}},"required":["events"]}},"required":["type","config"]}]},"TriggerType":{"type":"string","enum":["endpoint","slack"],"description":"Type of the trigger. The `slack` trigger type can be used only for `support` agent type."},"CommerceEventsTriggerType":{"type":"string","enum":["commerce_events"],"description":"Type of the trigger."},"AgentCollaborations":{"type":"array","description":"List of agent collaborations which allows an agent to hand off its task to other agents.","items":{"type":"object","properties":{"agentId":{"type":"string","description":"Identifier of the agent."},"description":{"type":"string","description":"Description of the agent collaboration."}}}},"NativeToolsResponse":{"type":"array","description":"List of native tools which agents should have access to.","items":{"oneOf":[{"$ref":"#/components/schemas/SlackNativeToolResponse"},{"$ref":"#/components/schemas/RagCustomNativeToolResponse"},{"$ref":"#/components/schemas/RagEmporixNativeToolResponse"}]}},"SlackNativeToolResponse":{"allOf":[{"$ref":"#/components/schemas/BaseNativeTool"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the tool."},"type":{"description":"For SlackNativeTool it has to be set to `slack`."},"config":{"$ref":"#/components/schemas/SlackNativeToolConfigResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"BaseNativeTool":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/NativeToolType"},"name":{"type":"string","description":"Name of the tool."},"enabled":{"type":"boolean","description":"An indicator whether the tool is enabled.","default":false}},"required":["type","name"]},"NativeToolType":{"type":"string","enum":["slack","rag_custom","rag_emporix"],"description":"Type of the native tool."},"SlackNativeToolConfigResponse":{"type":"object","properties":{"teamId":{"type":"string","description":"Unique identifier of the Slack workspace (team) associated with the request. Used to distinguish the source Slack environment when handling events or API calls."}},"required":["teamId"]},"MetadataResponse":{"allOf":[{"$ref":"#/components/schemas/MetadataRequest"},{"type":"object","properties":{"createdAt":{"description":"Date and time when the object was created. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`","type":"string"},"modifiedAt":{"description":"Date and time when the object was last modified. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`","type":"string"}},"required":["version","createdAt","modifiedAt"]}]},"MetadataRequest":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the object. The version is required during the update operation because of the optimistic locking mechanism."}},"required":["version"]},"RagCustomNativeToolResponse":{"allOf":[{"$ref":"#/components/schemas/BaseNativeTool"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the tool."},"type":{"description":"For `RagCustomNativeTool`, it has to be set to `rag_custom`."},"config":{"$ref":"#/components/schemas/RagCustomNativeToolConfigResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"RagCustomNativeToolConfigResponse":{"allOf":[{"$ref":"#/components/schemas/RagCustomNativeToolConfig"},{"type":"object","properties":{"databaseConfig":{"$ref":"#/components/schemas/RagCustomDatabaseNativeToolConfigResponse"},"embeddingConfig":{"$ref":"#/components/schemas/RagCustomEmbeddingNativeToolConfigResponse"}}}]},"RagCustomNativeToolConfig":{"type":"object","properties":{"prompt":{"type":"string","description":"The prompt for an agent. It should define when and why this tool is to be called."},"maxResults":{"type":"integer","default":5,"description":"The maximum number of results found in the Vector Database."}},"required":["prompt"]},"RagCustomDatabaseNativeToolConfigResponse":{"allOf":[{"$ref":"#/components/schemas/RagCustomDatabaseNativeToolConfig"},{"type":"object","properties":{"token":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"RagCustomDatabaseNativeToolConfig":{"type":"object","properties":{"url":{"type":"string","description":"URL of the database."},"type":{"allOf":[{"$ref":"#/components/schemas/RagCustomDatabaseType"}]},"entityType":{"allOf":[{"$ref":"#/components/schemas/RagEntityType"}]},"collectionName":{"type":"string","description":"Name of the database collection."}},"required":["url","type","entityType","collectionName"]},"RagCustomDatabaseType":{"type":"string","enum":["qdrant"],"description":"Type of the database."},"RagEntityType":{"type":"string","enum":["product"],"description":"Type of the entity which is stored in the given collection."},"ExpandableTokenResponse":{"oneOf":[{"$ref":"#/components/schemas/InnerTokenResponse"},{"$ref":"#/components/schemas/ExpandedTokenResponse"}],"description":"The full response representing token. If the `expand=token` is **not** used, then only `id` field is returned, otherwise all fields are returned."},"InnerTokenResponse":{"type":"object","properties":{"id":{"type":"string","description":"ID of the token."}}},"ExpandedTokenResponse":{"allOf":[{"$ref":"#/components/schemas/InnerTokenResponse"},{"type":"object","properties":{"name":{"type":"string","description":"Name of the token."},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"RagCustomEmbeddingNativeToolConfigResponse":{"allOf":[{"$ref":"#/components/schemas/RagCustomEmbeddingNativeToolConfig"},{"type":"object","properties":{"token":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"RagCustomEmbeddingNativeToolConfig":{"type":"object","properties":{"model":{"type":"string","description":"Name of the OpenAI LLM model which should be used to create embedding of user's input in order to perform search operation."}},"required":["model"]},"RagEmporixNativeToolResponse":{"allOf":[{"$ref":"#/components/schemas/BaseNativeTool"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the tool."},"type":{"description":"For `RagEmporixNativeTool`, it has to be set to `rag_emporix`."},"config":{"$ref":"#/components/schemas/RagEmporixNativeToolConfigResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"RagEmporixNativeToolConfigResponse":{"allOf":[{"$ref":"#/components/schemas/RagEmporixNativeToolConfig"},{"type":"object","properties":{"embeddingConfig":{"oneOf":[{"$ref":"#/components/schemas/EmporixOpenAiRagEmporixEmbeddingNativeToolConfig"},{"$ref":"#/components/schemas/OpenAiRagEmporixEmbeddingNativeToolConfigResponse"},{"$ref":"#/components/schemas/SelfHostedOllamaRagEmporixEmbeddingNativeToolConfigResponse"}]}}}]},"RagEmporixNativeToolConfig":{"type":"object","properties":{"prompt":{"type":"string","description":"The prompt for an agent. It should define when and why this tool is to be called."},"entityType":{"allOf":[{"$ref":"#/components/schemas/RagEntityType"}]},"indexedFields":{"type":"array","description":"This field specifies the fields of the given entityType that are used for generating embeddings. The provided values are then concatenated and converted to embeddings.","items":{"type":"object","properties":{"name":{"type":"string","description":"It can act as an alias for the field key. For example, if the 'name.en' key is provided then its alias could be 'English Name' and that value is used in embedding input."},"key":{"type":"string","description":"Unique value representing the entityType key."}},"required":["key"]}}},"required":["prompt","entityType","indexedFields"]},"EmporixOpenAiRagEmporixEmbeddingNativeToolConfig":{"type":"object","properties":{"provider":{"allOf":[{"$ref":"#/components/schemas/RagLlmProvider"}],"description":"For this type, it should be set to 'emporix_openai'."}},"required":["provider"]},"RagLlmProvider":{"type":"string","enum":["emporix_openai","openai","self_hosted_ollama"]},"OpenAiRagEmporixEmbeddingNativeToolConfigResponse":{"allOf":[{"$ref":"#/components/schemas/OpenAiRagEmporixEmbeddingNativeToolConfig"},{"type":"object","properties":{"token":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"OpenAiRagEmporixEmbeddingNativeToolConfig":{"type":"object","properties":{"provider":{"allOf":[{"$ref":"#/components/schemas/RagLlmProvider"}],"description":"For this type, it should be set to 'emporix_openai'."},"model":{"type":"string","description":"OpenAI LLM model to be used for generating embeddings for indexed products and user's input query."},"dimensions":{"type":"integer","description":"Number of dimensions of embedding.","minimum":128,"maximum":4096}},"required":["provider","model","dimensions"]},"SelfHostedOllamaRagEmporixEmbeddingNativeToolConfigResponse":{"allOf":[{"$ref":"#/components/schemas/SelfHostedOllamaRagEmporixEmbeddingNativeToolConfig"},{"type":"object","properties":{"token":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"SelfHostedOllamaRagEmporixEmbeddingNativeToolConfig":{"type":"object","properties":{"provider":{"allOf":[{"$ref":"#/components/schemas/RagLlmProvider"}],"description":"For this type, it should be set to 'self_hosted_ollama'."},"model":{"type":"string","description":"Ollama LLM model to be used for generating embeddings for indexed products and user's input query."},"dimensions":{"type":"integer","description":"Number of dimensions of embedding.","minimum":128,"maximum":4096},"url":{"type":"string","description":"Base URL where Ollama is hosted."}},"required":["provider","model","dimensions","url"]},"EmporixLlm":{"allOf":[{"$ref":"#/components/schemas/BaseLlm"},{"type":"object","properties":{"provider":{"type":"string","description":"Type of the LLM Provider. The `emporix_openai` allows using the OpenAI token provided by Emporix. The token usage is limited. When using this provider `apiKey` property can be omitted.","enum":["emporix_openai"]}},"required":["provider"]}]},"BaseLlm":{"type":"object","properties":{"model":{"type":"string","description":"The exact name of the model."},"temperature":{"type":"number","format":"float","description":"Value between 0.1 and 1.0 (inclusive), in steps of 0.1. The lower value the more creative (but less stable) the model is.","enum":[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.9,1]},"maxTokens":{"type":"integer","description":"The limit of tokens which agent can burn during one request session."}},"required":["model","temperature","maxTokens"]},"ApiKeyLlmResponse":{"allOf":[{"$ref":"#/components/schemas/ApiKeyLlm"},{"type":"object","properties":{"token":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"ApiKeyLlm":{"allOf":[{"$ref":"#/components/schemas/BaseLlm"},{"type":"object","properties":{"provider":{"$ref":"#/components/schemas/ApiKeyLlmProvider"}},"required":["provider"]}]},"ApiKeyLlmProvider":{"type":"string","description":"Type of the LLM Provider. The supported providers allows you to provide your own API key. When using this providers, the `apiKey` property cannot be omitted.","enum":["openai","google","anthropic"]},"SelfHostedLlmResponse":{"allOf":[{"$ref":"#/components/schemas/SelfHostedLlm"},{"type":"object","properties":{"selfHostedParams":{"$ref":"#/components/schemas/SelfHostedParamsResponse"}}}]},"SelfHostedLlm":{"allOf":[{"$ref":"#/components/schemas/BaseLlm"},{"type":"object","properties":{"provider":{"type":"string","description":"Type of the LLM Provider. The self-hosted LLM allows you to provide your own LLMs. When using this providers, the `selfHostedParams.url` property cannot be omitted.","enum":["self_hosted_ollama","self_hosted_vllm"]}},"required":["provider"]}]},"SelfHostedParamsResponse":{"allOf":[{"$ref":"#/components/schemas/SelfHostedParams"},{"type":"object","properties":{"authorizationHeaderToken":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"SelfHostedParams":{"type":"object","properties":{"url":{"type":"string","description":"Url of the self-hosted LLM."},"authorizationHeaderName":{"type":"string","description":"Name of the header required for authorization e.g. `Authorization`."}},"required":["url"]},"AgentMcpServersResponse":{"type":"array","description":"List of MCP servers which agents should have access to.","items":{"oneOf":[{"$ref":"#/components/schemas/CustomAgentMcpServerResponse"},{"$ref":"#/components/schemas/PredefinedAgentMcpServer"}]}},"CustomAgentMcpServerResponse":{"allOf":[{"$ref":"#/components/schemas/CustomAgentMcpServerRequest"},{"type":"object","properties":{"mcpServer":{"allOf":[{"$ref":"#/components/schemas/McpServerResponse"},{"description":"The full response representing MCP server. If the `expand=mcpServer` is **not** used, then only `id` field is returned, otherwise all fields are returned."}]}}}]},"CustomAgentMcpServerRequest":{"allOf":[{"$ref":"#/components/schemas/BaseAgentMcpServer"},{"type":"object","properties":{"type":{"description":"For `CustomMcpServer` it has to be set to `custom`."},"mcpServer":{"type":"object","properties":{"id":{"type":"string","description":"ID of the MCP server."}},"required":["id"]}},"required":["mcpServer"]}]},"BaseAgentMcpServer":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/McpServerType"}},"required":["type"]},"McpServerType":{"type":"string","enum":["custom","predefined"],"description":"Type of the MCP server. The `custom` type allows you to integrate with your own MCP server instance, while the `predefined` type allows you to integrate with one of the instances provided by Emporix."},"McpServerResponse":{"allOf":[{"$ref":"#/components/schemas/BaseMcpServer"},{"type":"object","properties":{"config":{"$ref":"#/components/schemas/McpServerConfigResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"BaseMcpServer":{"type":"object","description":"An object representing customer's own implementation of the MCP server.","properties":{"name":{"type":"string","description":"Name of the MCP server."},"enabled":{"type":"boolean","description":"An indicator whether the MCP server is enabled.","default":false},"transport":{"$ref":"#/components/schemas/CustomMcpServerTransportType"}}},"CustomMcpServerTransportType":{"type":"string","enum":["streamable_http","sse"],"description":"Type of the communication between the agent and the MCP server. The `streamable_http` protocol is recommended, since the `sse` protocol is deprecated."},"McpServerConfigResponse":{"allOf":[{"$ref":"#/components/schemas/McpServerConfig"},{"type":"object","properties":{"authorizationHeaderToken":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"McpServerConfig":{"type":"object","properties":{"url":{"type":"string","description":"URL of the MCP server."},"authorizationHeaderName":{"type":"string","description":"Name of the header required for authorization, e.g. `Authorization`."}},"required":["url"]},"PredefinedAgentMcpServer":{"allOf":[{"$ref":"#/components/schemas/BaseAgentMcpServer"},{"type":"object","properties":{"type":{"description":"For the `PredefinedMcpServer` it has to be set to `predefined`."},"domain":{"enum":["customer","extensibility","order","product","frontend"]},"tools":{"type":"array","description":"List of the tools which should be used by the agent from this particular MCP server.","items":{"type":"string"}}}}]},"HandOff":{"type":"boolean","description":"Indicates whether the agent is handOff or not. HandOff agents are special types of agents which can be called by other agents through `agentCollaborations` property and their configuration is hidden."},"AgentType":{"type":"string","description":"Type of the agent handling the request.","enum":["support","generic","complaint","anti_fraud"]},"AgentHandOffResponse":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentAndTemplateAndHandOff"},{"type":"object","properties":{"id":{"type":"string","description":"Identifier of the agent."},"handOff":{"allOf":[{"$ref":"#/components/schemas/HandOff"}]},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"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":""}},"responses":{"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"}}}}}},"paths":{"/ai-service/{tenant}/agentic/agents":{"get":{"summary":"Listing agents","operationId":"GET-ai-list-agents","responses":{"200":{"description":"List of agents.","content":{"application/json":{"schema":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/AgentResponse"},{"$ref":"#/components/schemas/AgentHandOffResponse"}]}}}}},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"}},"description":"Retrieves agent templates based on the provided query.","tags":["Agent"]}}}}
```

## Searching agents

> Searches for agents based on the provided query.

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent","description":"Manage Agents"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agent_read"]}],"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.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"parameters":{"header_Accept-Language":{"name":"Accept-Language","in":"header","required":false,"schema":{"type":"string"},"description":"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.\n\n* If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.\n* 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.\n* If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.\n"},"pageSize":{"schema":{"type":"string"},"in":"query","name":"pageSize","description":"The number of documents to be retrieved per page."},"pageNumber":{"schema":{"type":"string"},"in":"query","name":"pageNumber","description":"The page number to be retrieved. The size of the pages should be specified by the `pageSize` parameter."},"sort":{"schema":{"type":"string"},"in":"query","name":"sort","description":"List of properties used to sort the results, separated by colons."},"fields":{"schema":{"type":"string"},"in":"query","name":"fields","description":"Fields to be returned in the response."},"expand":{"schema":{"type":"string","enum":["mcpServers","nativeTools","token"]},"in":"query","name":"expand","description":"Fields to be expanded in the response. It means that instead of the object IDs, the whole objects are returned in the response."},"header_xTotalCount":{"schema":{"type":"boolean"},"in":"header","name":"X-Total-Count","description":"Flag indicating whether the total number of retrieved results should be returned."}},"schemas":{"AgentResponse":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentRequestAndResponse"},{"type":"object","properties":{"id":{"type":"string","description":"Identifier of the agent."},"nativeTools":{"$ref":"#/components/schemas/NativeToolsResponse"},"llmConfig":{"oneOf":[{"$ref":"#/components/schemas/EmporixLlm"},{"$ref":"#/components/schemas/ApiKeyLlmResponse"},{"$ref":"#/components/schemas/SelfHostedLlmResponse"}]},"mcpServers":{"$ref":"#/components/schemas/AgentMcpServersResponse"},"handOff":{"allOf":[{"$ref":"#/components/schemas/HandOff"}]},"type":{"$ref":"#/components/schemas/AgentType"},"templatePrompt":{"type":"string","description":"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."},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"BaseForAgentRequestAndResponse":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentAndTemplate"},{"type":"object","properties":{"triggers":{"type":"array","items":{"$ref":"#/components/schemas/AgentTrigger"}},"agentCollaborations":{"$ref":"#/components/schemas/AgentCollaborations"},"maxRecursionLimit":{"type":"integer","description":"Defines 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.","default":20,"minimum":1,"maximum":50},"enabledMemory":{"type":"boolean","description":"Defines whether the session memory should be stored between different agent calls.","default":false}},"required":["userPrompt","triggers"]}]},"BaseForAgentAndTemplate":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentAndTemplateAndHandOff"},{"type":"object","properties":{"userPrompt":{"type":"string","description":"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."},"icon":{"type":"string","description":"The fa class of react icon."},"tags":{"type":"array","items":{"type":"string","description":"Markers that allow you to categorize the agent."}},"enabled":{"type":"boolean","description":"Indicates whether the agent is enabled.","default":false}},"required":["name"]}]},"BaseForAgentAndTemplateAndHandOff":{"type":"object","properties":{"name":{"type":"object","description":"Localized name of the agent.","additionalProperties":{"type":"string"}},"description":{"type":"object","description":"Description of the agent.","additionalProperties":{"type":"string"}}}},"AgentTrigger":{"oneOf":[{"type":"object","properties":{"type":{"$ref":"#/components/schemas/TriggerType"}},"required":["type"]},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/CommerceEventsTriggerType"},"config":{"type":"object","description":"Additional configuration for the trigger.","properties":{"events":{"type":"string","description":"List of events that trigger the agent."}},"required":["events"]}},"required":["type","config"]}]},"TriggerType":{"type":"string","enum":["endpoint","slack"],"description":"Type of the trigger. The `slack` trigger type can be used only for `support` agent type."},"CommerceEventsTriggerType":{"type":"string","enum":["commerce_events"],"description":"Type of the trigger."},"AgentCollaborations":{"type":"array","description":"List of agent collaborations which allows an agent to hand off its task to other agents.","items":{"type":"object","properties":{"agentId":{"type":"string","description":"Identifier of the agent."},"description":{"type":"string","description":"Description of the agent collaboration."}}}},"NativeToolsResponse":{"type":"array","description":"List of native tools which agents should have access to.","items":{"oneOf":[{"$ref":"#/components/schemas/SlackNativeToolResponse"},{"$ref":"#/components/schemas/RagCustomNativeToolResponse"},{"$ref":"#/components/schemas/RagEmporixNativeToolResponse"}]}},"SlackNativeToolResponse":{"allOf":[{"$ref":"#/components/schemas/BaseNativeTool"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the tool."},"type":{"description":"For SlackNativeTool it has to be set to `slack`."},"config":{"$ref":"#/components/schemas/SlackNativeToolConfigResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"BaseNativeTool":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/NativeToolType"},"name":{"type":"string","description":"Name of the tool."},"enabled":{"type":"boolean","description":"An indicator whether the tool is enabled.","default":false}},"required":["type","name"]},"NativeToolType":{"type":"string","enum":["slack","rag_custom","rag_emporix"],"description":"Type of the native tool."},"SlackNativeToolConfigResponse":{"type":"object","properties":{"teamId":{"type":"string","description":"Unique identifier of the Slack workspace (team) associated with the request. Used to distinguish the source Slack environment when handling events or API calls."}},"required":["teamId"]},"MetadataResponse":{"allOf":[{"$ref":"#/components/schemas/MetadataRequest"},{"type":"object","properties":{"createdAt":{"description":"Date and time when the object was created. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`","type":"string"},"modifiedAt":{"description":"Date and time when the object was last modified. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`","type":"string"}},"required":["version","createdAt","modifiedAt"]}]},"MetadataRequest":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the object. The version is required during the update operation because of the optimistic locking mechanism."}},"required":["version"]},"RagCustomNativeToolResponse":{"allOf":[{"$ref":"#/components/schemas/BaseNativeTool"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the tool."},"type":{"description":"For `RagCustomNativeTool`, it has to be set to `rag_custom`."},"config":{"$ref":"#/components/schemas/RagCustomNativeToolConfigResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"RagCustomNativeToolConfigResponse":{"allOf":[{"$ref":"#/components/schemas/RagCustomNativeToolConfig"},{"type":"object","properties":{"databaseConfig":{"$ref":"#/components/schemas/RagCustomDatabaseNativeToolConfigResponse"},"embeddingConfig":{"$ref":"#/components/schemas/RagCustomEmbeddingNativeToolConfigResponse"}}}]},"RagCustomNativeToolConfig":{"type":"object","properties":{"prompt":{"type":"string","description":"The prompt for an agent. It should define when and why this tool is to be called."},"maxResults":{"type":"integer","default":5,"description":"The maximum number of results found in the Vector Database."}},"required":["prompt"]},"RagCustomDatabaseNativeToolConfigResponse":{"allOf":[{"$ref":"#/components/schemas/RagCustomDatabaseNativeToolConfig"},{"type":"object","properties":{"token":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"RagCustomDatabaseNativeToolConfig":{"type":"object","properties":{"url":{"type":"string","description":"URL of the database."},"type":{"allOf":[{"$ref":"#/components/schemas/RagCustomDatabaseType"}]},"entityType":{"allOf":[{"$ref":"#/components/schemas/RagEntityType"}]},"collectionName":{"type":"string","description":"Name of the database collection."}},"required":["url","type","entityType","collectionName"]},"RagCustomDatabaseType":{"type":"string","enum":["qdrant"],"description":"Type of the database."},"RagEntityType":{"type":"string","enum":["product"],"description":"Type of the entity which is stored in the given collection."},"ExpandableTokenResponse":{"oneOf":[{"$ref":"#/components/schemas/InnerTokenResponse"},{"$ref":"#/components/schemas/ExpandedTokenResponse"}],"description":"The full response representing token. If the `expand=token` is **not** used, then only `id` field is returned, otherwise all fields are returned."},"InnerTokenResponse":{"type":"object","properties":{"id":{"type":"string","description":"ID of the token."}}},"ExpandedTokenResponse":{"allOf":[{"$ref":"#/components/schemas/InnerTokenResponse"},{"type":"object","properties":{"name":{"type":"string","description":"Name of the token."},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"RagCustomEmbeddingNativeToolConfigResponse":{"allOf":[{"$ref":"#/components/schemas/RagCustomEmbeddingNativeToolConfig"},{"type":"object","properties":{"token":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"RagCustomEmbeddingNativeToolConfig":{"type":"object","properties":{"model":{"type":"string","description":"Name of the OpenAI LLM model which should be used to create embedding of user's input in order to perform search operation."}},"required":["model"]},"RagEmporixNativeToolResponse":{"allOf":[{"$ref":"#/components/schemas/BaseNativeTool"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the tool."},"type":{"description":"For `RagEmporixNativeTool`, it has to be set to `rag_emporix`."},"config":{"$ref":"#/components/schemas/RagEmporixNativeToolConfigResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"RagEmporixNativeToolConfigResponse":{"allOf":[{"$ref":"#/components/schemas/RagEmporixNativeToolConfig"},{"type":"object","properties":{"embeddingConfig":{"oneOf":[{"$ref":"#/components/schemas/EmporixOpenAiRagEmporixEmbeddingNativeToolConfig"},{"$ref":"#/components/schemas/OpenAiRagEmporixEmbeddingNativeToolConfigResponse"},{"$ref":"#/components/schemas/SelfHostedOllamaRagEmporixEmbeddingNativeToolConfigResponse"}]}}}]},"RagEmporixNativeToolConfig":{"type":"object","properties":{"prompt":{"type":"string","description":"The prompt for an agent. It should define when and why this tool is to be called."},"entityType":{"allOf":[{"$ref":"#/components/schemas/RagEntityType"}]},"indexedFields":{"type":"array","description":"This field specifies the fields of the given entityType that are used for generating embeddings. The provided values are then concatenated and converted to embeddings.","items":{"type":"object","properties":{"name":{"type":"string","description":"It can act as an alias for the field key. For example, if the 'name.en' key is provided then its alias could be 'English Name' and that value is used in embedding input."},"key":{"type":"string","description":"Unique value representing the entityType key."}},"required":["key"]}}},"required":["prompt","entityType","indexedFields"]},"EmporixOpenAiRagEmporixEmbeddingNativeToolConfig":{"type":"object","properties":{"provider":{"allOf":[{"$ref":"#/components/schemas/RagLlmProvider"}],"description":"For this type, it should be set to 'emporix_openai'."}},"required":["provider"]},"RagLlmProvider":{"type":"string","enum":["emporix_openai","openai","self_hosted_ollama"]},"OpenAiRagEmporixEmbeddingNativeToolConfigResponse":{"allOf":[{"$ref":"#/components/schemas/OpenAiRagEmporixEmbeddingNativeToolConfig"},{"type":"object","properties":{"token":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"OpenAiRagEmporixEmbeddingNativeToolConfig":{"type":"object","properties":{"provider":{"allOf":[{"$ref":"#/components/schemas/RagLlmProvider"}],"description":"For this type, it should be set to 'emporix_openai'."},"model":{"type":"string","description":"OpenAI LLM model to be used for generating embeddings for indexed products and user's input query."},"dimensions":{"type":"integer","description":"Number of dimensions of embedding.","minimum":128,"maximum":4096}},"required":["provider","model","dimensions"]},"SelfHostedOllamaRagEmporixEmbeddingNativeToolConfigResponse":{"allOf":[{"$ref":"#/components/schemas/SelfHostedOllamaRagEmporixEmbeddingNativeToolConfig"},{"type":"object","properties":{"token":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"SelfHostedOllamaRagEmporixEmbeddingNativeToolConfig":{"type":"object","properties":{"provider":{"allOf":[{"$ref":"#/components/schemas/RagLlmProvider"}],"description":"For this type, it should be set to 'self_hosted_ollama'."},"model":{"type":"string","description":"Ollama LLM model to be used for generating embeddings for indexed products and user's input query."},"dimensions":{"type":"integer","description":"Number of dimensions of embedding.","minimum":128,"maximum":4096},"url":{"type":"string","description":"Base URL where Ollama is hosted."}},"required":["provider","model","dimensions","url"]},"EmporixLlm":{"allOf":[{"$ref":"#/components/schemas/BaseLlm"},{"type":"object","properties":{"provider":{"type":"string","description":"Type of the LLM Provider. The `emporix_openai` allows using the OpenAI token provided by Emporix. The token usage is limited. When using this provider `apiKey` property can be omitted.","enum":["emporix_openai"]}},"required":["provider"]}]},"BaseLlm":{"type":"object","properties":{"model":{"type":"string","description":"The exact name of the model."},"temperature":{"type":"number","format":"float","description":"Value between 0.1 and 1.0 (inclusive), in steps of 0.1. The lower value the more creative (but less stable) the model is.","enum":[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.9,1]},"maxTokens":{"type":"integer","description":"The limit of tokens which agent can burn during one request session."}},"required":["model","temperature","maxTokens"]},"ApiKeyLlmResponse":{"allOf":[{"$ref":"#/components/schemas/ApiKeyLlm"},{"type":"object","properties":{"token":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"ApiKeyLlm":{"allOf":[{"$ref":"#/components/schemas/BaseLlm"},{"type":"object","properties":{"provider":{"$ref":"#/components/schemas/ApiKeyLlmProvider"}},"required":["provider"]}]},"ApiKeyLlmProvider":{"type":"string","description":"Type of the LLM Provider. The supported providers allows you to provide your own API key. When using this providers, the `apiKey` property cannot be omitted.","enum":["openai","google","anthropic"]},"SelfHostedLlmResponse":{"allOf":[{"$ref":"#/components/schemas/SelfHostedLlm"},{"type":"object","properties":{"selfHostedParams":{"$ref":"#/components/schemas/SelfHostedParamsResponse"}}}]},"SelfHostedLlm":{"allOf":[{"$ref":"#/components/schemas/BaseLlm"},{"type":"object","properties":{"provider":{"type":"string","description":"Type of the LLM Provider. The self-hosted LLM allows you to provide your own LLMs. When using this providers, the `selfHostedParams.url` property cannot be omitted.","enum":["self_hosted_ollama","self_hosted_vllm"]}},"required":["provider"]}]},"SelfHostedParamsResponse":{"allOf":[{"$ref":"#/components/schemas/SelfHostedParams"},{"type":"object","properties":{"authorizationHeaderToken":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"SelfHostedParams":{"type":"object","properties":{"url":{"type":"string","description":"Url of the self-hosted LLM."},"authorizationHeaderName":{"type":"string","description":"Name of the header required for authorization e.g. `Authorization`."}},"required":["url"]},"AgentMcpServersResponse":{"type":"array","description":"List of MCP servers which agents should have access to.","items":{"oneOf":[{"$ref":"#/components/schemas/CustomAgentMcpServerResponse"},{"$ref":"#/components/schemas/PredefinedAgentMcpServer"}]}},"CustomAgentMcpServerResponse":{"allOf":[{"$ref":"#/components/schemas/CustomAgentMcpServerRequest"},{"type":"object","properties":{"mcpServer":{"allOf":[{"$ref":"#/components/schemas/McpServerResponse"},{"description":"The full response representing MCP server. If the `expand=mcpServer` is **not** used, then only `id` field is returned, otherwise all fields are returned."}]}}}]},"CustomAgentMcpServerRequest":{"allOf":[{"$ref":"#/components/schemas/BaseAgentMcpServer"},{"type":"object","properties":{"type":{"description":"For `CustomMcpServer` it has to be set to `custom`."},"mcpServer":{"type":"object","properties":{"id":{"type":"string","description":"ID of the MCP server."}},"required":["id"]}},"required":["mcpServer"]}]},"BaseAgentMcpServer":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/McpServerType"}},"required":["type"]},"McpServerType":{"type":"string","enum":["custom","predefined"],"description":"Type of the MCP server. The `custom` type allows you to integrate with your own MCP server instance, while the `predefined` type allows you to integrate with one of the instances provided by Emporix."},"McpServerResponse":{"allOf":[{"$ref":"#/components/schemas/BaseMcpServer"},{"type":"object","properties":{"config":{"$ref":"#/components/schemas/McpServerConfigResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"BaseMcpServer":{"type":"object","description":"An object representing customer's own implementation of the MCP server.","properties":{"name":{"type":"string","description":"Name of the MCP server."},"enabled":{"type":"boolean","description":"An indicator whether the MCP server is enabled.","default":false},"transport":{"$ref":"#/components/schemas/CustomMcpServerTransportType"}}},"CustomMcpServerTransportType":{"type":"string","enum":["streamable_http","sse"],"description":"Type of the communication between the agent and the MCP server. The `streamable_http` protocol is recommended, since the `sse` protocol is deprecated."},"McpServerConfigResponse":{"allOf":[{"$ref":"#/components/schemas/McpServerConfig"},{"type":"object","properties":{"authorizationHeaderToken":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"McpServerConfig":{"type":"object","properties":{"url":{"type":"string","description":"URL of the MCP server."},"authorizationHeaderName":{"type":"string","description":"Name of the header required for authorization, e.g. `Authorization`."}},"required":["url"]},"PredefinedAgentMcpServer":{"allOf":[{"$ref":"#/components/schemas/BaseAgentMcpServer"},{"type":"object","properties":{"type":{"description":"For the `PredefinedMcpServer` it has to be set to `predefined`."},"domain":{"enum":["customer","extensibility","order","product","frontend"]},"tools":{"type":"array","description":"List of the tools which should be used by the agent from this particular MCP server.","items":{"type":"string"}}}}]},"HandOff":{"type":"boolean","description":"Indicates whether the agent is handOff or not. HandOff agents are special types of agents which can be called by other agents through `agentCollaborations` property and their configuration is hidden."},"AgentType":{"type":"string","description":"Type of the agent handling the request.","enum":["support","generic","complaint","anti_fraud"]},"AgentHandOffResponse":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentAndTemplateAndHandOff"},{"type":"object","properties":{"id":{"type":"string","description":"Identifier of the agent."},"handOff":{"allOf":[{"$ref":"#/components/schemas/HandOff"}]},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"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":""},"QParamSearchBody":{"type":"object","properties":{"q":{"type":"string","description":"A standard query parameter is used to search for specific values. \n\nSee: [Standard Practices - Query parameter](https://developer.emporix.io/api-references/standard-practices/q-param)\n"}}}},"responses":{"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"}}}}},"requestBodies":{"QParamSearchBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QParamSearchBody"}}}}}},"paths":{"/ai-service/{tenant}/agentic/agents/search":{"post":{"parameters":[{"$ref":"#/components/parameters/header_Accept-Language"},{"$ref":"#/components/parameters/pageSize"},{"$ref":"#/components/parameters/pageNumber"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/header_xTotalCount"}],"summary":"Searching agents","operationId":"POST-ai-search-agents","responses":{"200":{"description":"List of agents.","content":{"application/json":{"schema":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/AgentResponse"},{"$ref":"#/components/schemas/AgentHandOffResponse"}]}}}}},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"}},"requestBody":{"$ref":"#/components/requestBodies/QParamSearchBody"},"description":"Searches for agents based on the provided query.","tags":["Agent"]}}}}
```

## Retrieving agent by ID

> Retrieves the agent by given ID.

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent","description":"Manage Agents"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agent_read"]}],"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.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"parameters":{"header_Accept-Language":{"name":"Accept-Language","in":"header","required":false,"schema":{"type":"string"},"description":"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.\n\n* If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.\n* 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.\n* If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.\n"},"fields":{"schema":{"type":"string"},"in":"query","name":"fields","description":"Fields to be returned in the response."},"expand":{"schema":{"type":"string","enum":["mcpServers","nativeTools","token"]},"in":"query","name":"expand","description":"Fields to be expanded in the response. It means that instead of the object IDs, the whole objects are returned in the response."}},"schemas":{"AgentResponse":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentRequestAndResponse"},{"type":"object","properties":{"id":{"type":"string","description":"Identifier of the agent."},"nativeTools":{"$ref":"#/components/schemas/NativeToolsResponse"},"llmConfig":{"oneOf":[{"$ref":"#/components/schemas/EmporixLlm"},{"$ref":"#/components/schemas/ApiKeyLlmResponse"},{"$ref":"#/components/schemas/SelfHostedLlmResponse"}]},"mcpServers":{"$ref":"#/components/schemas/AgentMcpServersResponse"},"handOff":{"allOf":[{"$ref":"#/components/schemas/HandOff"}]},"type":{"$ref":"#/components/schemas/AgentType"},"templatePrompt":{"type":"string","description":"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."},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"BaseForAgentRequestAndResponse":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentAndTemplate"},{"type":"object","properties":{"triggers":{"type":"array","items":{"$ref":"#/components/schemas/AgentTrigger"}},"agentCollaborations":{"$ref":"#/components/schemas/AgentCollaborations"},"maxRecursionLimit":{"type":"integer","description":"Defines 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.","default":20,"minimum":1,"maximum":50},"enabledMemory":{"type":"boolean","description":"Defines whether the session memory should be stored between different agent calls.","default":false}},"required":["userPrompt","triggers"]}]},"BaseForAgentAndTemplate":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentAndTemplateAndHandOff"},{"type":"object","properties":{"userPrompt":{"type":"string","description":"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."},"icon":{"type":"string","description":"The fa class of react icon."},"tags":{"type":"array","items":{"type":"string","description":"Markers that allow you to categorize the agent."}},"enabled":{"type":"boolean","description":"Indicates whether the agent is enabled.","default":false}},"required":["name"]}]},"BaseForAgentAndTemplateAndHandOff":{"type":"object","properties":{"name":{"type":"object","description":"Localized name of the agent.","additionalProperties":{"type":"string"}},"description":{"type":"object","description":"Description of the agent.","additionalProperties":{"type":"string"}}}},"AgentTrigger":{"oneOf":[{"type":"object","properties":{"type":{"$ref":"#/components/schemas/TriggerType"}},"required":["type"]},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/CommerceEventsTriggerType"},"config":{"type":"object","description":"Additional configuration for the trigger.","properties":{"events":{"type":"string","description":"List of events that trigger the agent."}},"required":["events"]}},"required":["type","config"]}]},"TriggerType":{"type":"string","enum":["endpoint","slack"],"description":"Type of the trigger. The `slack` trigger type can be used only for `support` agent type."},"CommerceEventsTriggerType":{"type":"string","enum":["commerce_events"],"description":"Type of the trigger."},"AgentCollaborations":{"type":"array","description":"List of agent collaborations which allows an agent to hand off its task to other agents.","items":{"type":"object","properties":{"agentId":{"type":"string","description":"Identifier of the agent."},"description":{"type":"string","description":"Description of the agent collaboration."}}}},"NativeToolsResponse":{"type":"array","description":"List of native tools which agents should have access to.","items":{"oneOf":[{"$ref":"#/components/schemas/SlackNativeToolResponse"},{"$ref":"#/components/schemas/RagCustomNativeToolResponse"},{"$ref":"#/components/schemas/RagEmporixNativeToolResponse"}]}},"SlackNativeToolResponse":{"allOf":[{"$ref":"#/components/schemas/BaseNativeTool"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the tool."},"type":{"description":"For SlackNativeTool it has to be set to `slack`."},"config":{"$ref":"#/components/schemas/SlackNativeToolConfigResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"BaseNativeTool":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/NativeToolType"},"name":{"type":"string","description":"Name of the tool."},"enabled":{"type":"boolean","description":"An indicator whether the tool is enabled.","default":false}},"required":["type","name"]},"NativeToolType":{"type":"string","enum":["slack","rag_custom","rag_emporix"],"description":"Type of the native tool."},"SlackNativeToolConfigResponse":{"type":"object","properties":{"teamId":{"type":"string","description":"Unique identifier of the Slack workspace (team) associated with the request. Used to distinguish the source Slack environment when handling events or API calls."}},"required":["teamId"]},"MetadataResponse":{"allOf":[{"$ref":"#/components/schemas/MetadataRequest"},{"type":"object","properties":{"createdAt":{"description":"Date and time when the object was created. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`","type":"string"},"modifiedAt":{"description":"Date and time when the object was last modified. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`","type":"string"}},"required":["version","createdAt","modifiedAt"]}]},"MetadataRequest":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the object. The version is required during the update operation because of the optimistic locking mechanism."}},"required":["version"]},"RagCustomNativeToolResponse":{"allOf":[{"$ref":"#/components/schemas/BaseNativeTool"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the tool."},"type":{"description":"For `RagCustomNativeTool`, it has to be set to `rag_custom`."},"config":{"$ref":"#/components/schemas/RagCustomNativeToolConfigResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"RagCustomNativeToolConfigResponse":{"allOf":[{"$ref":"#/components/schemas/RagCustomNativeToolConfig"},{"type":"object","properties":{"databaseConfig":{"$ref":"#/components/schemas/RagCustomDatabaseNativeToolConfigResponse"},"embeddingConfig":{"$ref":"#/components/schemas/RagCustomEmbeddingNativeToolConfigResponse"}}}]},"RagCustomNativeToolConfig":{"type":"object","properties":{"prompt":{"type":"string","description":"The prompt for an agent. It should define when and why this tool is to be called."},"maxResults":{"type":"integer","default":5,"description":"The maximum number of results found in the Vector Database."}},"required":["prompt"]},"RagCustomDatabaseNativeToolConfigResponse":{"allOf":[{"$ref":"#/components/schemas/RagCustomDatabaseNativeToolConfig"},{"type":"object","properties":{"token":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"RagCustomDatabaseNativeToolConfig":{"type":"object","properties":{"url":{"type":"string","description":"URL of the database."},"type":{"allOf":[{"$ref":"#/components/schemas/RagCustomDatabaseType"}]},"entityType":{"allOf":[{"$ref":"#/components/schemas/RagEntityType"}]},"collectionName":{"type":"string","description":"Name of the database collection."}},"required":["url","type","entityType","collectionName"]},"RagCustomDatabaseType":{"type":"string","enum":["qdrant"],"description":"Type of the database."},"RagEntityType":{"type":"string","enum":["product"],"description":"Type of the entity which is stored in the given collection."},"ExpandableTokenResponse":{"oneOf":[{"$ref":"#/components/schemas/InnerTokenResponse"},{"$ref":"#/components/schemas/ExpandedTokenResponse"}],"description":"The full response representing token. If the `expand=token` is **not** used, then only `id` field is returned, otherwise all fields are returned."},"InnerTokenResponse":{"type":"object","properties":{"id":{"type":"string","description":"ID of the token."}}},"ExpandedTokenResponse":{"allOf":[{"$ref":"#/components/schemas/InnerTokenResponse"},{"type":"object","properties":{"name":{"type":"string","description":"Name of the token."},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"RagCustomEmbeddingNativeToolConfigResponse":{"allOf":[{"$ref":"#/components/schemas/RagCustomEmbeddingNativeToolConfig"},{"type":"object","properties":{"token":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"RagCustomEmbeddingNativeToolConfig":{"type":"object","properties":{"model":{"type":"string","description":"Name of the OpenAI LLM model which should be used to create embedding of user's input in order to perform search operation."}},"required":["model"]},"RagEmporixNativeToolResponse":{"allOf":[{"$ref":"#/components/schemas/BaseNativeTool"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the tool."},"type":{"description":"For `RagEmporixNativeTool`, it has to be set to `rag_emporix`."},"config":{"$ref":"#/components/schemas/RagEmporixNativeToolConfigResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"RagEmporixNativeToolConfigResponse":{"allOf":[{"$ref":"#/components/schemas/RagEmporixNativeToolConfig"},{"type":"object","properties":{"embeddingConfig":{"oneOf":[{"$ref":"#/components/schemas/EmporixOpenAiRagEmporixEmbeddingNativeToolConfig"},{"$ref":"#/components/schemas/OpenAiRagEmporixEmbeddingNativeToolConfigResponse"},{"$ref":"#/components/schemas/SelfHostedOllamaRagEmporixEmbeddingNativeToolConfigResponse"}]}}}]},"RagEmporixNativeToolConfig":{"type":"object","properties":{"prompt":{"type":"string","description":"The prompt for an agent. It should define when and why this tool is to be called."},"entityType":{"allOf":[{"$ref":"#/components/schemas/RagEntityType"}]},"indexedFields":{"type":"array","description":"This field specifies the fields of the given entityType that are used for generating embeddings. The provided values are then concatenated and converted to embeddings.","items":{"type":"object","properties":{"name":{"type":"string","description":"It can act as an alias for the field key. For example, if the 'name.en' key is provided then its alias could be 'English Name' and that value is used in embedding input."},"key":{"type":"string","description":"Unique value representing the entityType key."}},"required":["key"]}}},"required":["prompt","entityType","indexedFields"]},"EmporixOpenAiRagEmporixEmbeddingNativeToolConfig":{"type":"object","properties":{"provider":{"allOf":[{"$ref":"#/components/schemas/RagLlmProvider"}],"description":"For this type, it should be set to 'emporix_openai'."}},"required":["provider"]},"RagLlmProvider":{"type":"string","enum":["emporix_openai","openai","self_hosted_ollama"]},"OpenAiRagEmporixEmbeddingNativeToolConfigResponse":{"allOf":[{"$ref":"#/components/schemas/OpenAiRagEmporixEmbeddingNativeToolConfig"},{"type":"object","properties":{"token":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"OpenAiRagEmporixEmbeddingNativeToolConfig":{"type":"object","properties":{"provider":{"allOf":[{"$ref":"#/components/schemas/RagLlmProvider"}],"description":"For this type, it should be set to 'emporix_openai'."},"model":{"type":"string","description":"OpenAI LLM model to be used for generating embeddings for indexed products and user's input query."},"dimensions":{"type":"integer","description":"Number of dimensions of embedding.","minimum":128,"maximum":4096}},"required":["provider","model","dimensions"]},"SelfHostedOllamaRagEmporixEmbeddingNativeToolConfigResponse":{"allOf":[{"$ref":"#/components/schemas/SelfHostedOllamaRagEmporixEmbeddingNativeToolConfig"},{"type":"object","properties":{"token":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"SelfHostedOllamaRagEmporixEmbeddingNativeToolConfig":{"type":"object","properties":{"provider":{"allOf":[{"$ref":"#/components/schemas/RagLlmProvider"}],"description":"For this type, it should be set to 'self_hosted_ollama'."},"model":{"type":"string","description":"Ollama LLM model to be used for generating embeddings for indexed products and user's input query."},"dimensions":{"type":"integer","description":"Number of dimensions of embedding.","minimum":128,"maximum":4096},"url":{"type":"string","description":"Base URL where Ollama is hosted."}},"required":["provider","model","dimensions","url"]},"EmporixLlm":{"allOf":[{"$ref":"#/components/schemas/BaseLlm"},{"type":"object","properties":{"provider":{"type":"string","description":"Type of the LLM Provider. The `emporix_openai` allows using the OpenAI token provided by Emporix. The token usage is limited. When using this provider `apiKey` property can be omitted.","enum":["emporix_openai"]}},"required":["provider"]}]},"BaseLlm":{"type":"object","properties":{"model":{"type":"string","description":"The exact name of the model."},"temperature":{"type":"number","format":"float","description":"Value between 0.1 and 1.0 (inclusive), in steps of 0.1. The lower value the more creative (but less stable) the model is.","enum":[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.9,1]},"maxTokens":{"type":"integer","description":"The limit of tokens which agent can burn during one request session."}},"required":["model","temperature","maxTokens"]},"ApiKeyLlmResponse":{"allOf":[{"$ref":"#/components/schemas/ApiKeyLlm"},{"type":"object","properties":{"token":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"ApiKeyLlm":{"allOf":[{"$ref":"#/components/schemas/BaseLlm"},{"type":"object","properties":{"provider":{"$ref":"#/components/schemas/ApiKeyLlmProvider"}},"required":["provider"]}]},"ApiKeyLlmProvider":{"type":"string","description":"Type of the LLM Provider. The supported providers allows you to provide your own API key. When using this providers, the `apiKey` property cannot be omitted.","enum":["openai","google","anthropic"]},"SelfHostedLlmResponse":{"allOf":[{"$ref":"#/components/schemas/SelfHostedLlm"},{"type":"object","properties":{"selfHostedParams":{"$ref":"#/components/schemas/SelfHostedParamsResponse"}}}]},"SelfHostedLlm":{"allOf":[{"$ref":"#/components/schemas/BaseLlm"},{"type":"object","properties":{"provider":{"type":"string","description":"Type of the LLM Provider. The self-hosted LLM allows you to provide your own LLMs. When using this providers, the `selfHostedParams.url` property cannot be omitted.","enum":["self_hosted_ollama","self_hosted_vllm"]}},"required":["provider"]}]},"SelfHostedParamsResponse":{"allOf":[{"$ref":"#/components/schemas/SelfHostedParams"},{"type":"object","properties":{"authorizationHeaderToken":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"SelfHostedParams":{"type":"object","properties":{"url":{"type":"string","description":"Url of the self-hosted LLM."},"authorizationHeaderName":{"type":"string","description":"Name of the header required for authorization e.g. `Authorization`."}},"required":["url"]},"AgentMcpServersResponse":{"type":"array","description":"List of MCP servers which agents should have access to.","items":{"oneOf":[{"$ref":"#/components/schemas/CustomAgentMcpServerResponse"},{"$ref":"#/components/schemas/PredefinedAgentMcpServer"}]}},"CustomAgentMcpServerResponse":{"allOf":[{"$ref":"#/components/schemas/CustomAgentMcpServerRequest"},{"type":"object","properties":{"mcpServer":{"allOf":[{"$ref":"#/components/schemas/McpServerResponse"},{"description":"The full response representing MCP server. If the `expand=mcpServer` is **not** used, then only `id` field is returned, otherwise all fields are returned."}]}}}]},"CustomAgentMcpServerRequest":{"allOf":[{"$ref":"#/components/schemas/BaseAgentMcpServer"},{"type":"object","properties":{"type":{"description":"For `CustomMcpServer` it has to be set to `custom`."},"mcpServer":{"type":"object","properties":{"id":{"type":"string","description":"ID of the MCP server."}},"required":["id"]}},"required":["mcpServer"]}]},"BaseAgentMcpServer":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/McpServerType"}},"required":["type"]},"McpServerType":{"type":"string","enum":["custom","predefined"],"description":"Type of the MCP server. The `custom` type allows you to integrate with your own MCP server instance, while the `predefined` type allows you to integrate with one of the instances provided by Emporix."},"McpServerResponse":{"allOf":[{"$ref":"#/components/schemas/BaseMcpServer"},{"type":"object","properties":{"config":{"$ref":"#/components/schemas/McpServerConfigResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"BaseMcpServer":{"type":"object","description":"An object representing customer's own implementation of the MCP server.","properties":{"name":{"type":"string","description":"Name of the MCP server."},"enabled":{"type":"boolean","description":"An indicator whether the MCP server is enabled.","default":false},"transport":{"$ref":"#/components/schemas/CustomMcpServerTransportType"}}},"CustomMcpServerTransportType":{"type":"string","enum":["streamable_http","sse"],"description":"Type of the communication between the agent and the MCP server. The `streamable_http` protocol is recommended, since the `sse` protocol is deprecated."},"McpServerConfigResponse":{"allOf":[{"$ref":"#/components/schemas/McpServerConfig"},{"type":"object","properties":{"authorizationHeaderToken":{"$ref":"#/components/schemas/ExpandableTokenResponse"}}}]},"McpServerConfig":{"type":"object","properties":{"url":{"type":"string","description":"URL of the MCP server."},"authorizationHeaderName":{"type":"string","description":"Name of the header required for authorization, e.g. `Authorization`."}},"required":["url"]},"PredefinedAgentMcpServer":{"allOf":[{"$ref":"#/components/schemas/BaseAgentMcpServer"},{"type":"object","properties":{"type":{"description":"For the `PredefinedMcpServer` it has to be set to `predefined`."},"domain":{"enum":["customer","extensibility","order","product","frontend"]},"tools":{"type":"array","description":"List of the tools which should be used by the agent from this particular MCP server.","items":{"type":"string"}}}}]},"HandOff":{"type":"boolean","description":"Indicates whether the agent is handOff or not. HandOff agents are special types of agents which can be called by other agents through `agentCollaborations` property and their configuration is hidden."},"AgentType":{"type":"string","description":"Type of the agent handling the request.","enum":["support","generic","complaint","anti_fraud"]},"AgentHandOffResponse":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentAndTemplateAndHandOff"},{"type":"object","properties":{"id":{"type":"string","description":"Identifier of the agent."},"handOff":{"allOf":[{"$ref":"#/components/schemas/HandOff"}]},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"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":""}},"responses":{"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"}}}},"404_resp_common":{"description":"Example response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}},"paths":{"/ai-service/{tenant}/agentic/agents/{agentId}":{"get":{"parameters":[{"$ref":"#/components/parameters/header_Accept-Language"},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/expand"}],"summary":"Retrieving agent by ID","operationId":"GET-ai-retrieve-agent","responses":{"200":{"description":"A single agent.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AgentResponse"},{"$ref":"#/components/schemas/AgentHandOffResponse"}]}}}},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"},"404":{"$ref":"#/components/responses/404_resp_common"}},"description":"Retrieves the agent by given ID.","tags":["Agent"]}}}}
```

## Upserting agent

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

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent","description":"Manage Agents"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agent_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.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"parameters":{"header_Content-Language":{"name":"Content-Language","in":"header","required":false,"schema":{"type":"string"},"description":"List of languages in which localized fields in the request body are provided.\n\n* 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.\n* If the header is set to a specific language, the localized fields should be provided as strings.\n* If the header is empty, the endpoint assumes that the localized fields are provided in the default language defined in the Configuration Service.\n\n**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.\n"}},"schemas":{"IdResponse":{"type":"object","properties":{"id":{"type":"string","description":"Identifier of the resource."}}},"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"}}}}}}},"AgentRequest":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentRequestAndResponse"},{"type":"object","properties":{"nativeTools":{"type":"array","items":{"$ref":"#/components/schemas/IdWrapper"},"description":"ID of the native tools."},"llmConfig":{"oneOf":[{"$ref":"#/components/schemas/EmporixLlm"},{"$ref":"#/components/schemas/ApiKeyLlmRequest"},{"$ref":"#/components/schemas/SelfHostedLlmRequest"}]},"mcpServers":{"$ref":"#/components/schemas/AgentMcpServersRequest"},"metadata":{"$ref":"#/components/schemas/MetadataRequest"}},"required":["llmConfig","mcpServers"]}]},"BaseForAgentRequestAndResponse":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentAndTemplate"},{"type":"object","properties":{"triggers":{"type":"array","items":{"$ref":"#/components/schemas/AgentTrigger"}},"agentCollaborations":{"$ref":"#/components/schemas/AgentCollaborations"},"maxRecursionLimit":{"type":"integer","description":"Defines 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.","default":20,"minimum":1,"maximum":50},"enabledMemory":{"type":"boolean","description":"Defines whether the session memory should be stored between different agent calls.","default":false}},"required":["userPrompt","triggers"]}]},"BaseForAgentAndTemplate":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentAndTemplateAndHandOff"},{"type":"object","properties":{"userPrompt":{"type":"string","description":"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."},"icon":{"type":"string","description":"The fa class of react icon."},"tags":{"type":"array","items":{"type":"string","description":"Markers that allow you to categorize the agent."}},"enabled":{"type":"boolean","description":"Indicates whether the agent is enabled.","default":false}},"required":["name"]}]},"BaseForAgentAndTemplateAndHandOff":{"type":"object","properties":{"name":{"type":"object","description":"Localized name of the agent.","additionalProperties":{"type":"string"}},"description":{"type":"object","description":"Description of the agent.","additionalProperties":{"type":"string"}}}},"AgentTrigger":{"oneOf":[{"type":"object","properties":{"type":{"$ref":"#/components/schemas/TriggerType"}},"required":["type"]},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/CommerceEventsTriggerType"},"config":{"type":"object","description":"Additional configuration for the trigger.","properties":{"events":{"type":"string","description":"List of events that trigger the agent."}},"required":["events"]}},"required":["type","config"]}]},"TriggerType":{"type":"string","enum":["endpoint","slack"],"description":"Type of the trigger. The `slack` trigger type can be used only for `support` agent type."},"CommerceEventsTriggerType":{"type":"string","enum":["commerce_events"],"description":"Type of the trigger."},"AgentCollaborations":{"type":"array","description":"List of agent collaborations which allows an agent to hand off its task to other agents.","items":{"type":"object","properties":{"agentId":{"type":"string","description":"Identifier of the agent."},"description":{"type":"string","description":"Description of the agent collaboration."}}}},"IdWrapper":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]},"EmporixLlm":{"allOf":[{"$ref":"#/components/schemas/BaseLlm"},{"type":"object","properties":{"provider":{"type":"string","description":"Type of the LLM Provider. The `emporix_openai` allows using the OpenAI token provided by Emporix. The token usage is limited. When using this provider `apiKey` property can be omitted.","enum":["emporix_openai"]}},"required":["provider"]}]},"BaseLlm":{"type":"object","properties":{"model":{"type":"string","description":"The exact name of the model."},"temperature":{"type":"number","format":"float","description":"Value between 0.1 and 1.0 (inclusive), in steps of 0.1. The lower value the more creative (but less stable) the model is.","enum":[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.9,1]},"maxTokens":{"type":"integer","description":"The limit of tokens which agent can burn during one request session."}},"required":["model","temperature","maxTokens"]},"ApiKeyLlmRequest":{"allOf":[{"$ref":"#/components/schemas/ApiKeyLlm"},{"type":"object","properties":{"token":{"$ref":"#/components/schemas/InnerTokenRequest"}},"required":["token"]}]},"ApiKeyLlm":{"allOf":[{"$ref":"#/components/schemas/BaseLlm"},{"type":"object","properties":{"provider":{"$ref":"#/components/schemas/ApiKeyLlmProvider"}},"required":["provider"]}]},"ApiKeyLlmProvider":{"type":"string","description":"Type of the LLM Provider. The supported providers allows you to provide your own API key. When using this providers, the `apiKey` property cannot be omitted.","enum":["openai","google","anthropic"]},"InnerTokenRequest":{"type":"object","properties":{"id":{"type":"string","description":"ID of the token."}},"required":["id"]},"SelfHostedLlmRequest":{"allOf":[{"$ref":"#/components/schemas/SelfHostedLlm"},{"type":"object","properties":{"selfHostedParams":{"$ref":"#/components/schemas/SelfHostedParamsRequest"}},"required":["selfHostedParams"]}]},"SelfHostedLlm":{"allOf":[{"$ref":"#/components/schemas/BaseLlm"},{"type":"object","properties":{"provider":{"type":"string","description":"Type of the LLM Provider. The self-hosted LLM allows you to provide your own LLMs. When using this providers, the `selfHostedParams.url` property cannot be omitted.","enum":["self_hosted_ollama","self_hosted_vllm"]}},"required":["provider"]}]},"SelfHostedParamsRequest":{"allOf":[{"$ref":"#/components/schemas/SelfHostedParams"},{"type":"object"},{"properties":{"authorizationHeaderToken":{"$ref":"#/components/schemas/InnerTokenRequest"}}}]},"SelfHostedParams":{"type":"object","properties":{"url":{"type":"string","description":"Url of the self-hosted LLM."},"authorizationHeaderName":{"type":"string","description":"Name of the header required for authorization e.g. `Authorization`."}},"required":["url"]},"AgentMcpServersRequest":{"type":"array","description":"List of MCP servers which agents should have access to.","items":{"oneOf":[{"$ref":"#/components/schemas/CustomAgentMcpServerRequest"},{"$ref":"#/components/schemas/PredefinedAgentMcpServer"}]}},"CustomAgentMcpServerRequest":{"allOf":[{"$ref":"#/components/schemas/BaseAgentMcpServer"},{"type":"object","properties":{"type":{"description":"For `CustomMcpServer` it has to be set to `custom`."},"mcpServer":{"type":"object","properties":{"id":{"type":"string","description":"ID of the MCP server."}},"required":["id"]}},"required":["mcpServer"]}]},"BaseAgentMcpServer":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/McpServerType"}},"required":["type"]},"McpServerType":{"type":"string","enum":["custom","predefined"],"description":"Type of the MCP server. The `custom` type allows you to integrate with your own MCP server instance, while the `predefined` type allows you to integrate with one of the instances provided by Emporix."},"PredefinedAgentMcpServer":{"allOf":[{"$ref":"#/components/schemas/BaseAgentMcpServer"},{"type":"object","properties":{"type":{"description":"For the `PredefinedMcpServer` it has to be set to `predefined`."},"domain":{"enum":["customer","extensibility","order","product","frontend"]},"tools":{"type":"array","description":"List of the tools which should be used by the agent from this particular MCP server.","items":{"type":"string"}}}}]},"MetadataRequest":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the object. The version is required during the update operation because of the optimistic locking mechanism."}},"required":["version"]}},"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"}}}},"404_resp_common":{"description":"Example response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"409_resp_common":{"description":"There are three possible reasons:\n 1. Resource with given code already exists, please choose unique code for your resource\n 2. 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.\n 3. 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.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"requestBodies":{"agentUpsertBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRequest"}}}}}},"paths":{"/ai-service/{tenant}/agentic/agents/{agentId}":{"put":{"parameters":[{"$ref":"#/components/parameters/header_Content-Language"}],"summary":"Upserting agent","operationId":"PUT-ai-agent","responses":{"201":{"description":"ID of created agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdResponse"}}}},"204":{"description":"The resource has been successfully updated."},"400":{"$ref":"#/components/responses/400_resp_common"},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"},"404":{"$ref":"#/components/responses/404_resp_common"},"409":{"$ref":"#/components/responses/409_resp_common"}},"description":"Updates or creates a specified product by replacing all of its existing data with data from the request body.\nIf the `metadata.version` is provided then optimistic locking is enabled and version must match the version in the database.","requestBody":{"$ref":"#/components/requestBodies/agentUpsertBody"},"tags":["Agent"]}}}}
```

## Deleting agent

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

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent","description":"Manage Agents"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agent_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.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"parameters":{"force":{"schema":{"type":"boolean"},"in":"query","name":"force","description":"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."}},"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"}}}},"404_resp_common":{"description":"Example response","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"}}}}}}}}},"paths":{"/ai-service/{tenant}/agentic/agents/{agentId}":{"delete":{"summary":"Deleting agent","operationId":"DELETE-ai-delete-agent","parameters":[{"$ref":"#/components/parameters/force"}],"responses":{"204":{"description":"Given agent has been deleted."},"400":{"$ref":"#/components/responses/400_resp_common"},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"},"404":{"$ref":"#/components/responses/404_resp_common"}},"description":"Deletes agent by given ID.\n\n***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`.","tags":["Agent"]}}}}
```

## Partially updating agent

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

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent","description":"Manage Agents"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agent_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.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"}}}},"404_resp_common":{"description":"Example response","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"}}}}}}},"PatchRequest":{"type":"array","description":"Partial update operation list.","items":{"type":"object","properties":{"op":{"anyOf":[{"enum":["ADD","REMOVE","REPLACE"]}],"type":"string"},"path":{"type":"string"},"value":{"anyOf":[{"type":"string","description":"Value of the string type."},{"type":"object","description":"Any part of the details object."}]}},"required":["op","path"]}}},"requestBodies":{"agentPatchBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchRequest"}}}}}},"paths":{"/ai-service/{tenant}/agentic/agents/{agentId}":{"patch":{"summary":"Partially updating agent","operationId":"PATCH-ai-update-agent","responses":{"204":{"description":"No Content"},"400":{"$ref":"#/components/responses/400_resp_common"},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"},"404":{"$ref":"#/components/responses/404_resp_common"}},"description":"Partially updates a single agent document with given information.\nSingle update may contain multiple partial updates in the form of an array. It contains the allowed operations list:\n  - `add` (adding an item to the items list)\n  - `remove` (removing an item from the items list)\n  - `replace` (replacing an item with given ID with new definition)","requestBody":{"$ref":"#/components/requestBodies/agentPatchBody"},"tags":["Agent"]}}}}
```