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

# 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.agentexecution_manage":"Needed to execute agentic chat.","ai.agentexecution_manage_own":"Needed to execute agentic chat by customers.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"schemas":{"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":{"deprecated":true,"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/AgentMetadataResponse"},"versions":{"type":"array","description":"Stored history of previous agent configurations. Present only when the request sets `allVersions=true`. Omitted otherwise.","items":{"$ref":"#/components/schemas/AgentVersion"}}}}]},"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 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.","default":false}},"required":["userPrompt","triggers"]}]},"BaseForAgentAndTemplate":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentAndTemplateAndHandOff"},{"type":"object","properties":{"requiredScopes":{"type":"array","description":"Defines which caller types are allowed to execute the agent.\nAuthorization is evaluated with OR semantics: access is granted if the caller\nmatches at least one configured value.\nIf this field is missing or empty, no scope-based restriction is applied.\n\nMatching rules:\n- anonymous: always grants access.\n- customer: requires scope `ai.agentexecution_manage_own`.\n- employee: requires scope `ai.agentexecution_manage`.\n- integration: requires scope `ai.agentexecution_manage`.\n\nIf no configured value matches, request is rejected with 403 Forbidden.\n","items":{"type":"string","enum":["anonymous","customer","employee","integration"]}},"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."}},"outputFormat":{"type":"string","description":"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.\n"},"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."},"filter":{"$ref":"#/components/schemas/CommerceEventTriggerFilter"},"eventScopes":{"type":"array","description":"Optional IAM scopes used to obtain an Emporix token when the agent runs from a Commerce Event. When omitted or empty, the agent does not receive `emporix-token`. Each value must be a scope the caller is allowed to grant.","items":{"type":"string"},"uniqueItems":true}},"required":["events"]}},"required":["type","config"]}]},"TriggerType":{"type":"string","enum":["endpoint","slack","teams"],"description":"Type of the trigger. When `slack` or `teams` is selected, the agent must have exactly one matching enabled Slack or Teams native tool assigned."},"CommerceEventsTriggerType":{"type":"string","enum":["commerce_events"],"description":"Type of the trigger."},"CommerceEventTriggerFilter":{"oneOf":[{"$ref":"#/components/schemas/CommerceEventTriggerLeafFilter"},{"$ref":"#/components/schemas/CommerceEventTriggerCompoundFilter"}],"description":"Optional filter expression applied to commerce event payloads. When set, the agent is triggered only if the event payload matches the filter."},"CommerceEventTriggerLeafFilter":{"description":"Filter condition applied to a single field in the commerce event payload.","oneOf":[{"$ref":"#/components/schemas/CommerceEventTriggerLeafFilterNoRight"},{"$ref":"#/components/schemas/CommerceEventTriggerLeafFilterScalarRight"},{"$ref":"#/components/schemas/CommerceEventTriggerLeafFilterArrayRight"}]},"CommerceEventTriggerLeafFilterNoRight":{"type":"object","description":"Filter condition for unary operators that do not accept `right`.","properties":{"left":{"type":"string","description":"Dot-notation path to a field in the commerce event payload."},"op":{"type":"string","enum":["$exists","$notExists","$isEmpty","$notEmpty"]}},"required":["left","op"],"additionalProperties":false},"CommerceEventTriggerLeafFilterScalarRight":{"type":"object","description":"Filter condition for scalar comparison operators.","properties":{"left":{"type":"string","description":"Dot-notation path to a field in the commerce event payload."},"op":{"type":"string","enum":["$eq","$ne"]},"right":{"$ref":"#/components/schemas/CommerceEventTriggerFilterScalarValue"}},"required":["left","op","right"],"additionalProperties":false},"CommerceEventTriggerFilterScalarValue":{"description":"Scalar value used in commerce event filter comparisons.","oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"CommerceEventTriggerLeafFilterArrayRight":{"type":"object","description":"Filter condition for array membership operators.","properties":{"left":{"type":"string","description":"Dot-notation path to a field in the commerce event payload."},"op":{"type":"string","enum":["$in","$notIn"]},"right":{"$ref":"#/components/schemas/CommerceEventTriggerFilterScalarArrayValue"}},"required":["left","op","right"],"additionalProperties":false},"CommerceEventTriggerFilterScalarArrayValue":{"type":"array","description":"Array value used by list-based operators in commerce event filters.","items":{"$ref":"#/components/schemas/CommerceEventTriggerFilterScalarValue"},"minItems":1},"CommerceEventTriggerCompoundFilter":{"type":"object","description":"Filter that combines multiple conditions using logical operators.","properties":{"op":{"$ref":"#/components/schemas/CommerceEventTriggerFilterLogicalOperator"},"conditions":{"type":"array","description":"Nested filter conditions combined by the logical operator.","items":{"$ref":"#/components/schemas/CommerceEventTriggerFilter"},"minItems":1}},"required":["op","conditions"]},"CommerceEventTriggerFilterLogicalOperator":{"type":"string","enum":["$and","$or"],"description":"Logical operator used to combine multiple filter conditions."},"AgentCollaborations":{"type":"array","description":"List of agent collaborations which allows an agent to hand off its task to other agents. Collaborations remain in the caller's session and do not enable memory by themselves.","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"},{"$ref":"#/components/schemas/TeamsNativeToolResponse"}]}},"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","teams"],"description":"Type of the native tool. Possible values:\n* `slack`\n* `rag_custom`\n* `rag_emporix`\n* `teams`"},"SlackNativeToolConfigResponse":{"type":"object","description":"Configuration of a Slack native tool instance.","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."},"defaultInboundAgentId":{"type":"string","description":"Agent ID that handles inbound Slack replies when no conversation-specific routing context exists yet."},"allowedOperations":{"type":"array","items":{"$ref":"#/components/schemas/SlackAllowedOperations"},"description":"Operations the tool instance exposes to assigned agents. At least one value is required when the tool is enabled."}},"required":["teamId"]},"SlackAllowedOperations":{"type":"string","enum":["sendMessage","createChannel","inviteParticipants","collaborateOnChannel"],"description":"Slack native tool operation identifier."},"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-30T13: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-30T13: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/IdResponse"},{"$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."},"IdResponse":{"type":"object","properties":{"id":{"type":"string","description":"Identifier of the resource."}}},"ExpandedTokenResponse":{"allOf":[{"$ref":"#/components/schemas/IdResponse"},{"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":{"type":"string","description":"Type of the entity which is stored in the given collection. Supported predefined types: [ORDER, PRODUCT] and custom entity types."},"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"]}},"filterFields":{"type":"array","description":"This field specifies the fields of the given entityType that are used for filtering the data before performing actual search.","items":{"type":"object","properties":{"description":{"type":"string","description":"It should contain the description of the field, so LLM is able to know when to use this field in order to filter the data. For enums, possible values should be specified here."},"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"]},"TeamsNativeToolResponse":{"allOf":[{"$ref":"#/components/schemas/BaseNativeTool"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the tool."},"type":{"description":"For TeamsNativeTool it has to be set to `teams`."},"config":{"$ref":"#/components/schemas/TeamsNativeToolConfigResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"TeamsNativeToolConfigResponse":{"type":"object","description":"Configuration of an MS Teams native tool instance.","properties":{"teamId":{"type":"string","description":"Microsoft Teams team ID the tool is bound to."},"tenantId":{"type":"string","description":"Customer Azure AD tenant ID for the Teams workspace."},"defaultInboundAgentId":{"type":"string","description":"Agent ID that handles inbound Teams replies when no conversation-specific owner is set."},"allowedOperations":{"type":"array","items":{"$ref":"#/components/schemas/TeamsAllowedOperations"},"description":"Operations the tool instance exposes to assigned agents. At least one value is required when the tool is enabled."}},"required":["teamId"]},"TeamsAllowedOperations":{"type":"string","enum":["sendMessage","createChat","createChannel","inviteParticipants","collaborateOnChannel","collaborateOnChat"],"description":"MS Teams native tool operation identifier."},"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."},"additionalParams":{"type":"object","additionalProperties":true,"description":"Optional JSON object of extra model parameters. Use it to pass provider-specific options, for example reasoning settings.\n"}},"required":["model"]},"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"]},"baseProvider":{"type":"string","description":"Optional. Indicates which cloud LLM provider API the self-hosted endpoint is compatible with (OPENAI, GOOGLE, or ANTHROPIC). Applies when provider is self_hosted_ollama or self_hosted_vllm. Used to select the correct request/response conventions for that backend. Ignored for non–self-hosted providers.","enum":["ANTHROPIC","GOOGLE","OPENAI"]}},"required":["provider"]}]},"SelfHostedParamsResponse":{"allOf":[{"$ref":"#/components/schemas/SelfHostedParams"},{"type":"object","properties":{"authorizationHeaderToken":{"$ref":"#/components/schemas/ExpandableTokenResponse"},"oauth":{"$ref":"#/components/schemas/ExpandableOAuthResponse"}}}]},"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`."},"fileProcessingConfig":{"$ref":"#/components/schemas/FileProcessingConfig"}},"required":["url"]},"FileProcessingConfig":{"description":"Optional additional config for file processing (preview).\n\n**The `fileProcessingConfig` field is in preview mode** - some of the features may not be fully operational yet.","type":"object","properties":{"useResponsesApi":{"type":"boolean","description":"When true, file processing uses the Responses API on the self-hosted LLM."},"extraModelKey":{"type":"string","description":"Optional extra model identifier used for file processing."}}},"ExpandableOAuthResponse":{"oneOf":[{"$ref":"#/components/schemas/IdResponse"},{"$ref":"#/components/schemas/OAuthResponse"}],"description":"The full response representing OAuth. If the `expand=oauth` is **not** used, then only `id` field is returned, otherwise all fields are returned."},"OAuthResponse":{"allOf":[{"$ref":"#/components/schemas/OAuth"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the entity."},"clientSecretToken":{"$ref":"#/components/schemas/ExpandableTokenResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"OAuth":{"type":"object","description":"OAuth 2.0 client-credentials settings for authenticating with a self-hosted LLM backend.","properties":{"url":{"type":"string","format":"uri","description":"Token endpoint URL of the OAuth 2.0 authorization server used to request an access token."},"clientId":{"type":"string","description":"OAuth 2.0 client identifier registered with the authorization server."},"grantType":{"type":"string","description":"OAuth 2.0 grant type used to obtain an access token. Currently only `client_credentials` is supported.","enum":["client_credentials"]},"scope":{"type":"string","description":"Optional space-separated list of scopes to request for the access token."},"enabled":{"type":"boolean","description":"Indicates whether the OAuth configuration is enabled."}},"required":["url","clientId","grantType"]},"AgentMcpServersResponse":{"type":"array","description":"List of MCP servers which agents should have access to.","items":{"$ref":"#/components/schemas/AgentMcpServerResponse"}},"AgentMcpServerResponse":{"type":"object","required":["type"],"properties":{"type":{"$ref":"#/components/schemas/McpServerType"},"mcpServer":{"allOf":[{"$ref":"#/components/schemas/McpServerResponse"},{"description":"Present for `custom` and `dynamic` attachments. If `expand=mcpServer` is **not** used, then only the `id` field is returned, otherwise all fields are returned."}]},"domain":{"enum":["customer","extensibility","order","product","frontend"],"description":"Present for `predefined` attachments."},"tools":{"type":"array","description":"Tool-name allow-list. Present for `predefined` attachments and for `dynamic` attachments when a subset is configured. Omitted on `dynamic` means all enabled tools on the MCP server.","items":{"type":"string"}}}},"McpServerType":{"type":"string","enum":["custom","predefined","dynamic"],"description":"Type of the MCP server attachment on an agent. The `custom` type references a tenant-managed MCP server with a URL. The `predefined` type references an Emporix domain MCP server. The `dynamic` type references a tenant-managed dynamic MCP server and may include an optional tool-name allow-list."},"McpServerResponse":{"oneOf":[{"$ref":"#/components/schemas/CustomMcpServerResponse"},{"$ref":"#/components/schemas/DynamicMcpServerResponse"}]},"CustomMcpServerResponse":{"allOf":[{"$ref":"#/components/schemas/BaseManagedMcpServer"},{"type":"object","description":"An object representing customer's own implementation of the MCP server.","properties":{"id":{"type":"string","description":"Unique identifier of the MCP server."},"type":{"allOf":[{"$ref":"#/components/schemas/ManagedMcpServerType"}],"description":"Type of the managed MCP server resource."},"config":{"$ref":"#/components/schemas/McpServerConfigResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"BaseManagedMcpServer":{"type":"object","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 as transport for custom MCP servers."},"ManagedMcpServerType":{"type":"string","enum":["custom","dynamic"],"description":"Type of the managed MCP server resource. Possible values:\n* `custom`\n* `dynamic`\n\n  **The `dynamic` value is in preview mode** - some of the features may not be fully operational yet."},"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"]},"DynamicMcpServerResponse":{"allOf":[{"$ref":"#/components/schemas/BaseManagedMcpServer"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the MCP server."},"type":{"allOf":[{"$ref":"#/components/schemas/ManagedMcpServerType"}],"description":"For dynamic MCP servers it has to be set to `dynamic`."},"tools":{"type":"array","description":"List of tools exposed by this MCP server.\n\n**The `tools` field is in preview mode** - some of the features may not be fully operational yet.","items":{"$ref":"#/components/schemas/McpToolResponse"}},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"McpToolResponse":{"type":"object","description":"Tool definition for a dynamic MCP server.\n\n**Dynamic MCP tools are in preview mode** - some of the features may not be fully operational yet.","properties":{"name":{"type":"string","description":"Unique name of the tool. Contains only letters, numbers, and underscores."},"description":{"type":"string","description":"Human-readable description of the tool."},"prompt":{"type":"string","description":"Prompt that defines when and why the agent should call this tool."},"enabled":{"type":"boolean","description":"An indicator whether the tool is enabled."},"config":{"$ref":"#/components/schemas/McpToolConfigResponse"}}},"McpToolConfigResponse":{"type":"object","properties":{"requiredScopes":{"type":"array","description":"OAuth scopes required to invoke the tool.","items":{"type":"string"}},"inputSchema":{"type":"string","description":"JSON Schema document describing the tool input, provided as a JSON string."},"invocation":{"$ref":"#/components/schemas/McpToolInvocationResponse"}}},"McpToolInvocationResponse":{"type":"object","properties":{"functionId":{"type":"string","description":"Identifier of the Automation function to invoke when the tool is called."},"method":{"$ref":"#/components/schemas/McpToolInvocationMethod"},"argsLocation":{"$ref":"#/components/schemas/McpToolInvocationArgsLocation"}}},"McpToolInvocationMethod":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"description":"HTTP method used to invoke the Automation function."},"McpToolInvocationArgsLocation":{"type":"string","enum":["body","query"],"description":"Location of the tool arguments in the HTTP request. Defaults to `body` when omitted."},"HandOff":{"type":"boolean","deprecated":true,"description":"Deprecated. Indicates whether the agent is a hand-off agent. This field is no longer used. Clients should ignore it."},"AgentType":{"type":"string","description":"Type of the agent handling the request.","enum":["generic","complaint","anti_fraud"]},"AgentMetadataResponse":{"allOf":[{"$ref":"#/components/schemas/MetadataResponse"},{"type":"object","properties":{"modifiedBy":{"$ref":"#/components/schemas/ModifiedBy"},"changeNote":{"type":"string","description":"Note stored for this live version."}}}]},"ModifiedBy":{"type":"object","description":"Who last changed the agent.","required":["type"],"properties":{"type":{"type":"string","enum":["CUSTOMER","EMPLOYEE","EXTERNAL","SYSTEM"],"description":"Identity recorded for the change. `EXTERNAL` is assigned when the request authenticates with an API token. `SYSTEM` is used for automatic updates.\n"},"id":{"type":"string","description":"Identifier of the customer or employee. Omitted for `EXTERNAL` and `SYSTEM`. `id` is the `Hybris-User-Id` header value when `CUSTOMER` or `EMPLOYEE`."},"firstName":{"type":"string","description":"First name of the customer or employee."},"lastName":{"type":"string","description":"Last name of the customer or employee."}}},"AgentVersion":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentRequestAndResponse"},{"type":"object","properties":{"templatePrompt":{"type":"string","description":"Prompt inherited from the template at the time of this version."},"nativeTools":{"$ref":"#/components/schemas/NativeToolsResponse"},"llmConfig":{"oneOf":[{"$ref":"#/components/schemas/EmporixLlm"},{"$ref":"#/components/schemas/ApiKeyLlmResponse"},{"$ref":"#/components/schemas/SelfHostedLlmResponse"}]},"mcpServers":{"$ref":"#/components/schemas/AgentMcpServersResponse"},"metadata":{"$ref":"#/components/schemas/AgentVersionMetadata"}},"required":["metadata"]}]},"AgentVersionMetadata":{"type":"object","required":["version"],"properties":{"version":{"type":"integer","minimum":1,"description":"Version number of this archived snapshot."},"modifiedAt":{"type":"string","description":"Date and time when this version was stored. The value is an ISO-8601 instant. For example: `2022-04-30T13:18:02.379Z`"},"modifiedBy":{"$ref":"#/components/schemas/ModifiedBy"},"changeNote":{"type":"string","description":"Note stored with this snapshot."}}},"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":{"$ref":"#/components/schemas/AgentResponse"}}}}},"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.agentexecution_manage":"Needed to execute agentic chat.","ai.agentexecution_manage_own":"Needed to execute agentic chat by customers.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"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":["oauth","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":{"deprecated":true,"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/AgentMetadataResponse"},"versions":{"type":"array","description":"Stored history of previous agent configurations. Present only when the request sets `allVersions=true`. Omitted otherwise.","items":{"$ref":"#/components/schemas/AgentVersion"}}}}]},"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 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.","default":false}},"required":["userPrompt","triggers"]}]},"BaseForAgentAndTemplate":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentAndTemplateAndHandOff"},{"type":"object","properties":{"requiredScopes":{"type":"array","description":"Defines which caller types are allowed to execute the agent.\nAuthorization is evaluated with OR semantics: access is granted if the caller\nmatches at least one configured value.\nIf this field is missing or empty, no scope-based restriction is applied.\n\nMatching rules:\n- anonymous: always grants access.\n- customer: requires scope `ai.agentexecution_manage_own`.\n- employee: requires scope `ai.agentexecution_manage`.\n- integration: requires scope `ai.agentexecution_manage`.\n\nIf no configured value matches, request is rejected with 403 Forbidden.\n","items":{"type":"string","enum":["anonymous","customer","employee","integration"]}},"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."}},"outputFormat":{"type":"string","description":"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.\n"},"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."},"filter":{"$ref":"#/components/schemas/CommerceEventTriggerFilter"},"eventScopes":{"type":"array","description":"Optional IAM scopes used to obtain an Emporix token when the agent runs from a Commerce Event. When omitted or empty, the agent does not receive `emporix-token`. Each value must be a scope the caller is allowed to grant.","items":{"type":"string"},"uniqueItems":true}},"required":["events"]}},"required":["type","config"]}]},"TriggerType":{"type":"string","enum":["endpoint","slack","teams"],"description":"Type of the trigger. When `slack` or `teams` is selected, the agent must have exactly one matching enabled Slack or Teams native tool assigned."},"CommerceEventsTriggerType":{"type":"string","enum":["commerce_events"],"description":"Type of the trigger."},"CommerceEventTriggerFilter":{"oneOf":[{"$ref":"#/components/schemas/CommerceEventTriggerLeafFilter"},{"$ref":"#/components/schemas/CommerceEventTriggerCompoundFilter"}],"description":"Optional filter expression applied to commerce event payloads. When set, the agent is triggered only if the event payload matches the filter."},"CommerceEventTriggerLeafFilter":{"description":"Filter condition applied to a single field in the commerce event payload.","oneOf":[{"$ref":"#/components/schemas/CommerceEventTriggerLeafFilterNoRight"},{"$ref":"#/components/schemas/CommerceEventTriggerLeafFilterScalarRight"},{"$ref":"#/components/schemas/CommerceEventTriggerLeafFilterArrayRight"}]},"CommerceEventTriggerLeafFilterNoRight":{"type":"object","description":"Filter condition for unary operators that do not accept `right`.","properties":{"left":{"type":"string","description":"Dot-notation path to a field in the commerce event payload."},"op":{"type":"string","enum":["$exists","$notExists","$isEmpty","$notEmpty"]}},"required":["left","op"],"additionalProperties":false},"CommerceEventTriggerLeafFilterScalarRight":{"type":"object","description":"Filter condition for scalar comparison operators.","properties":{"left":{"type":"string","description":"Dot-notation path to a field in the commerce event payload."},"op":{"type":"string","enum":["$eq","$ne"]},"right":{"$ref":"#/components/schemas/CommerceEventTriggerFilterScalarValue"}},"required":["left","op","right"],"additionalProperties":false},"CommerceEventTriggerFilterScalarValue":{"description":"Scalar value used in commerce event filter comparisons.","oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"CommerceEventTriggerLeafFilterArrayRight":{"type":"object","description":"Filter condition for array membership operators.","properties":{"left":{"type":"string","description":"Dot-notation path to a field in the commerce event payload."},"op":{"type":"string","enum":["$in","$notIn"]},"right":{"$ref":"#/components/schemas/CommerceEventTriggerFilterScalarArrayValue"}},"required":["left","op","right"],"additionalProperties":false},"CommerceEventTriggerFilterScalarArrayValue":{"type":"array","description":"Array value used by list-based operators in commerce event filters.","items":{"$ref":"#/components/schemas/CommerceEventTriggerFilterScalarValue"},"minItems":1},"CommerceEventTriggerCompoundFilter":{"type":"object","description":"Filter that combines multiple conditions using logical operators.","properties":{"op":{"$ref":"#/components/schemas/CommerceEventTriggerFilterLogicalOperator"},"conditions":{"type":"array","description":"Nested filter conditions combined by the logical operator.","items":{"$ref":"#/components/schemas/CommerceEventTriggerFilter"},"minItems":1}},"required":["op","conditions"]},"CommerceEventTriggerFilterLogicalOperator":{"type":"string","enum":["$and","$or"],"description":"Logical operator used to combine multiple filter conditions."},"AgentCollaborations":{"type":"array","description":"List of agent collaborations which allows an agent to hand off its task to other agents. Collaborations remain in the caller's session and do not enable memory by themselves.","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"},{"$ref":"#/components/schemas/TeamsNativeToolResponse"}]}},"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","teams"],"description":"Type of the native tool. Possible values:\n* `slack`\n* `rag_custom`\n* `rag_emporix`\n* `teams`"},"SlackNativeToolConfigResponse":{"type":"object","description":"Configuration of a Slack native tool instance.","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."},"defaultInboundAgentId":{"type":"string","description":"Agent ID that handles inbound Slack replies when no conversation-specific routing context exists yet."},"allowedOperations":{"type":"array","items":{"$ref":"#/components/schemas/SlackAllowedOperations"},"description":"Operations the tool instance exposes to assigned agents. At least one value is required when the tool is enabled."}},"required":["teamId"]},"SlackAllowedOperations":{"type":"string","enum":["sendMessage","createChannel","inviteParticipants","collaborateOnChannel"],"description":"Slack native tool operation identifier."},"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-30T13: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-30T13: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/IdResponse"},{"$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."},"IdResponse":{"type":"object","properties":{"id":{"type":"string","description":"Identifier of the resource."}}},"ExpandedTokenResponse":{"allOf":[{"$ref":"#/components/schemas/IdResponse"},{"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":{"type":"string","description":"Type of the entity which is stored in the given collection. Supported predefined types: [ORDER, PRODUCT] and custom entity types."},"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"]}},"filterFields":{"type":"array","description":"This field specifies the fields of the given entityType that are used for filtering the data before performing actual search.","items":{"type":"object","properties":{"description":{"type":"string","description":"It should contain the description of the field, so LLM is able to know when to use this field in order to filter the data. For enums, possible values should be specified here."},"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"]},"TeamsNativeToolResponse":{"allOf":[{"$ref":"#/components/schemas/BaseNativeTool"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the tool."},"type":{"description":"For TeamsNativeTool it has to be set to `teams`."},"config":{"$ref":"#/components/schemas/TeamsNativeToolConfigResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"TeamsNativeToolConfigResponse":{"type":"object","description":"Configuration of an MS Teams native tool instance.","properties":{"teamId":{"type":"string","description":"Microsoft Teams team ID the tool is bound to."},"tenantId":{"type":"string","description":"Customer Azure AD tenant ID for the Teams workspace."},"defaultInboundAgentId":{"type":"string","description":"Agent ID that handles inbound Teams replies when no conversation-specific owner is set."},"allowedOperations":{"type":"array","items":{"$ref":"#/components/schemas/TeamsAllowedOperations"},"description":"Operations the tool instance exposes to assigned agents. At least one value is required when the tool is enabled."}},"required":["teamId"]},"TeamsAllowedOperations":{"type":"string","enum":["sendMessage","createChat","createChannel","inviteParticipants","collaborateOnChannel","collaborateOnChat"],"description":"MS Teams native tool operation identifier."},"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."},"additionalParams":{"type":"object","additionalProperties":true,"description":"Optional JSON object of extra model parameters. Use it to pass provider-specific options, for example reasoning settings.\n"}},"required":["model"]},"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"]},"baseProvider":{"type":"string","description":"Optional. Indicates which cloud LLM provider API the self-hosted endpoint is compatible with (OPENAI, GOOGLE, or ANTHROPIC). Applies when provider is self_hosted_ollama or self_hosted_vllm. Used to select the correct request/response conventions for that backend. Ignored for non–self-hosted providers.","enum":["ANTHROPIC","GOOGLE","OPENAI"]}},"required":["provider"]}]},"SelfHostedParamsResponse":{"allOf":[{"$ref":"#/components/schemas/SelfHostedParams"},{"type":"object","properties":{"authorizationHeaderToken":{"$ref":"#/components/schemas/ExpandableTokenResponse"},"oauth":{"$ref":"#/components/schemas/ExpandableOAuthResponse"}}}]},"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`."},"fileProcessingConfig":{"$ref":"#/components/schemas/FileProcessingConfig"}},"required":["url"]},"FileProcessingConfig":{"description":"Optional additional config for file processing (preview).\n\n**The `fileProcessingConfig` field is in preview mode** - some of the features may not be fully operational yet.","type":"object","properties":{"useResponsesApi":{"type":"boolean","description":"When true, file processing uses the Responses API on the self-hosted LLM."},"extraModelKey":{"type":"string","description":"Optional extra model identifier used for file processing."}}},"ExpandableOAuthResponse":{"oneOf":[{"$ref":"#/components/schemas/IdResponse"},{"$ref":"#/components/schemas/OAuthResponse"}],"description":"The full response representing OAuth. If the `expand=oauth` is **not** used, then only `id` field is returned, otherwise all fields are returned."},"OAuthResponse":{"allOf":[{"$ref":"#/components/schemas/OAuth"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the entity."},"clientSecretToken":{"$ref":"#/components/schemas/ExpandableTokenResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"OAuth":{"type":"object","description":"OAuth 2.0 client-credentials settings for authenticating with a self-hosted LLM backend.","properties":{"url":{"type":"string","format":"uri","description":"Token endpoint URL of the OAuth 2.0 authorization server used to request an access token."},"clientId":{"type":"string","description":"OAuth 2.0 client identifier registered with the authorization server."},"grantType":{"type":"string","description":"OAuth 2.0 grant type used to obtain an access token. Currently only `client_credentials` is supported.","enum":["client_credentials"]},"scope":{"type":"string","description":"Optional space-separated list of scopes to request for the access token."},"enabled":{"type":"boolean","description":"Indicates whether the OAuth configuration is enabled."}},"required":["url","clientId","grantType"]},"AgentMcpServersResponse":{"type":"array","description":"List of MCP servers which agents should have access to.","items":{"$ref":"#/components/schemas/AgentMcpServerResponse"}},"AgentMcpServerResponse":{"type":"object","required":["type"],"properties":{"type":{"$ref":"#/components/schemas/McpServerType"},"mcpServer":{"allOf":[{"$ref":"#/components/schemas/McpServerResponse"},{"description":"Present for `custom` and `dynamic` attachments. If `expand=mcpServer` is **not** used, then only the `id` field is returned, otherwise all fields are returned."}]},"domain":{"enum":["customer","extensibility","order","product","frontend"],"description":"Present for `predefined` attachments."},"tools":{"type":"array","description":"Tool-name allow-list. Present for `predefined` attachments and for `dynamic` attachments when a subset is configured. Omitted on `dynamic` means all enabled tools on the MCP server.","items":{"type":"string"}}}},"McpServerType":{"type":"string","enum":["custom","predefined","dynamic"],"description":"Type of the MCP server attachment on an agent. The `custom` type references a tenant-managed MCP server with a URL. The `predefined` type references an Emporix domain MCP server. The `dynamic` type references a tenant-managed dynamic MCP server and may include an optional tool-name allow-list."},"McpServerResponse":{"oneOf":[{"$ref":"#/components/schemas/CustomMcpServerResponse"},{"$ref":"#/components/schemas/DynamicMcpServerResponse"}]},"CustomMcpServerResponse":{"allOf":[{"$ref":"#/components/schemas/BaseManagedMcpServer"},{"type":"object","description":"An object representing customer's own implementation of the MCP server.","properties":{"id":{"type":"string","description":"Unique identifier of the MCP server."},"type":{"allOf":[{"$ref":"#/components/schemas/ManagedMcpServerType"}],"description":"Type of the managed MCP server resource."},"config":{"$ref":"#/components/schemas/McpServerConfigResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"BaseManagedMcpServer":{"type":"object","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 as transport for custom MCP servers."},"ManagedMcpServerType":{"type":"string","enum":["custom","dynamic"],"description":"Type of the managed MCP server resource. Possible values:\n* `custom`\n* `dynamic`\n\n  **The `dynamic` value is in preview mode** - some of the features may not be fully operational yet."},"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"]},"DynamicMcpServerResponse":{"allOf":[{"$ref":"#/components/schemas/BaseManagedMcpServer"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the MCP server."},"type":{"allOf":[{"$ref":"#/components/schemas/ManagedMcpServerType"}],"description":"For dynamic MCP servers it has to be set to `dynamic`."},"tools":{"type":"array","description":"List of tools exposed by this MCP server.\n\n**The `tools` field is in preview mode** - some of the features may not be fully operational yet.","items":{"$ref":"#/components/schemas/McpToolResponse"}},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"McpToolResponse":{"type":"object","description":"Tool definition for a dynamic MCP server.\n\n**Dynamic MCP tools are in preview mode** - some of the features may not be fully operational yet.","properties":{"name":{"type":"string","description":"Unique name of the tool. Contains only letters, numbers, and underscores."},"description":{"type":"string","description":"Human-readable description of the tool."},"prompt":{"type":"string","description":"Prompt that defines when and why the agent should call this tool."},"enabled":{"type":"boolean","description":"An indicator whether the tool is enabled."},"config":{"$ref":"#/components/schemas/McpToolConfigResponse"}}},"McpToolConfigResponse":{"type":"object","properties":{"requiredScopes":{"type":"array","description":"OAuth scopes required to invoke the tool.","items":{"type":"string"}},"inputSchema":{"type":"string","description":"JSON Schema document describing the tool input, provided as a JSON string."},"invocation":{"$ref":"#/components/schemas/McpToolInvocationResponse"}}},"McpToolInvocationResponse":{"type":"object","properties":{"functionId":{"type":"string","description":"Identifier of the Automation function to invoke when the tool is called."},"method":{"$ref":"#/components/schemas/McpToolInvocationMethod"},"argsLocation":{"$ref":"#/components/schemas/McpToolInvocationArgsLocation"}}},"McpToolInvocationMethod":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"description":"HTTP method used to invoke the Automation function."},"McpToolInvocationArgsLocation":{"type":"string","enum":["body","query"],"description":"Location of the tool arguments in the HTTP request. Defaults to `body` when omitted."},"HandOff":{"type":"boolean","deprecated":true,"description":"Deprecated. Indicates whether the agent is a hand-off agent. This field is no longer used. Clients should ignore it."},"AgentType":{"type":"string","description":"Type of the agent handling the request.","enum":["generic","complaint","anti_fraud"]},"AgentMetadataResponse":{"allOf":[{"$ref":"#/components/schemas/MetadataResponse"},{"type":"object","properties":{"modifiedBy":{"$ref":"#/components/schemas/ModifiedBy"},"changeNote":{"type":"string","description":"Note stored for this live version."}}}]},"ModifiedBy":{"type":"object","description":"Who last changed the agent.","required":["type"],"properties":{"type":{"type":"string","enum":["CUSTOMER","EMPLOYEE","EXTERNAL","SYSTEM"],"description":"Identity recorded for the change. `EXTERNAL` is assigned when the request authenticates with an API token. `SYSTEM` is used for automatic updates.\n"},"id":{"type":"string","description":"Identifier of the customer or employee. Omitted for `EXTERNAL` and `SYSTEM`. `id` is the `Hybris-User-Id` header value when `CUSTOMER` or `EMPLOYEE`."},"firstName":{"type":"string","description":"First name of the customer or employee."},"lastName":{"type":"string","description":"Last name of the customer or employee."}}},"AgentVersion":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentRequestAndResponse"},{"type":"object","properties":{"templatePrompt":{"type":"string","description":"Prompt inherited from the template at the time of this version."},"nativeTools":{"$ref":"#/components/schemas/NativeToolsResponse"},"llmConfig":{"oneOf":[{"$ref":"#/components/schemas/EmporixLlm"},{"$ref":"#/components/schemas/ApiKeyLlmResponse"},{"$ref":"#/components/schemas/SelfHostedLlmResponse"}]},"mcpServers":{"$ref":"#/components/schemas/AgentMcpServersResponse"},"metadata":{"$ref":"#/components/schemas/AgentVersionMetadata"}},"required":["metadata"]}]},"AgentVersionMetadata":{"type":"object","required":["version"],"properties":{"version":{"type":"integer","minimum":1,"description":"Version number of this archived snapshot."},"modifiedAt":{"type":"string","description":"Date and time when this version was stored. The value is an ISO-8601 instant. For example: `2022-04-30T13:18:02.379Z`"},"modifiedBy":{"$ref":"#/components/schemas/ModifiedBy"},"changeNote":{"type":"string","description":"Note stored with this snapshot."}}},"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-documentation/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":{"$ref":"#/components/schemas/AgentResponse"}}}}},"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.agentexecution_manage":"Needed to execute agentic chat.","ai.agentexecution_manage_own":"Needed to execute agentic chat by customers.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"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":["oauth","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."},"agentVersion":{"name":"version","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Returns the configuration stored for this agent version. Omit the parameter to return the live agent.\nThe response is `404` when the agent or this version does not exist.\nCannot be combined with `allVersions` query parameter.\n"},"allVersions":{"name":"allVersions","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"When `true`, the response includes `versions` field containing the stored history of previous configurations.\nCannot be combined with `version` query parameter.\n"}},"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":{"deprecated":true,"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/AgentMetadataResponse"},"versions":{"type":"array","description":"Stored history of previous agent configurations. Present only when the request sets `allVersions=true`. Omitted otherwise.","items":{"$ref":"#/components/schemas/AgentVersion"}}}}]},"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 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.","default":false}},"required":["userPrompt","triggers"]}]},"BaseForAgentAndTemplate":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentAndTemplateAndHandOff"},{"type":"object","properties":{"requiredScopes":{"type":"array","description":"Defines which caller types are allowed to execute the agent.\nAuthorization is evaluated with OR semantics: access is granted if the caller\nmatches at least one configured value.\nIf this field is missing or empty, no scope-based restriction is applied.\n\nMatching rules:\n- anonymous: always grants access.\n- customer: requires scope `ai.agentexecution_manage_own`.\n- employee: requires scope `ai.agentexecution_manage`.\n- integration: requires scope `ai.agentexecution_manage`.\n\nIf no configured value matches, request is rejected with 403 Forbidden.\n","items":{"type":"string","enum":["anonymous","customer","employee","integration"]}},"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."}},"outputFormat":{"type":"string","description":"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.\n"},"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."},"filter":{"$ref":"#/components/schemas/CommerceEventTriggerFilter"},"eventScopes":{"type":"array","description":"Optional IAM scopes used to obtain an Emporix token when the agent runs from a Commerce Event. When omitted or empty, the agent does not receive `emporix-token`. Each value must be a scope the caller is allowed to grant.","items":{"type":"string"},"uniqueItems":true}},"required":["events"]}},"required":["type","config"]}]},"TriggerType":{"type":"string","enum":["endpoint","slack","teams"],"description":"Type of the trigger. When `slack` or `teams` is selected, the agent must have exactly one matching enabled Slack or Teams native tool assigned."},"CommerceEventsTriggerType":{"type":"string","enum":["commerce_events"],"description":"Type of the trigger."},"CommerceEventTriggerFilter":{"oneOf":[{"$ref":"#/components/schemas/CommerceEventTriggerLeafFilter"},{"$ref":"#/components/schemas/CommerceEventTriggerCompoundFilter"}],"description":"Optional filter expression applied to commerce event payloads. When set, the agent is triggered only if the event payload matches the filter."},"CommerceEventTriggerLeafFilter":{"description":"Filter condition applied to a single field in the commerce event payload.","oneOf":[{"$ref":"#/components/schemas/CommerceEventTriggerLeafFilterNoRight"},{"$ref":"#/components/schemas/CommerceEventTriggerLeafFilterScalarRight"},{"$ref":"#/components/schemas/CommerceEventTriggerLeafFilterArrayRight"}]},"CommerceEventTriggerLeafFilterNoRight":{"type":"object","description":"Filter condition for unary operators that do not accept `right`.","properties":{"left":{"type":"string","description":"Dot-notation path to a field in the commerce event payload."},"op":{"type":"string","enum":["$exists","$notExists","$isEmpty","$notEmpty"]}},"required":["left","op"],"additionalProperties":false},"CommerceEventTriggerLeafFilterScalarRight":{"type":"object","description":"Filter condition for scalar comparison operators.","properties":{"left":{"type":"string","description":"Dot-notation path to a field in the commerce event payload."},"op":{"type":"string","enum":["$eq","$ne"]},"right":{"$ref":"#/components/schemas/CommerceEventTriggerFilterScalarValue"}},"required":["left","op","right"],"additionalProperties":false},"CommerceEventTriggerFilterScalarValue":{"description":"Scalar value used in commerce event filter comparisons.","oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"CommerceEventTriggerLeafFilterArrayRight":{"type":"object","description":"Filter condition for array membership operators.","properties":{"left":{"type":"string","description":"Dot-notation path to a field in the commerce event payload."},"op":{"type":"string","enum":["$in","$notIn"]},"right":{"$ref":"#/components/schemas/CommerceEventTriggerFilterScalarArrayValue"}},"required":["left","op","right"],"additionalProperties":false},"CommerceEventTriggerFilterScalarArrayValue":{"type":"array","description":"Array value used by list-based operators in commerce event filters.","items":{"$ref":"#/components/schemas/CommerceEventTriggerFilterScalarValue"},"minItems":1},"CommerceEventTriggerCompoundFilter":{"type":"object","description":"Filter that combines multiple conditions using logical operators.","properties":{"op":{"$ref":"#/components/schemas/CommerceEventTriggerFilterLogicalOperator"},"conditions":{"type":"array","description":"Nested filter conditions combined by the logical operator.","items":{"$ref":"#/components/schemas/CommerceEventTriggerFilter"},"minItems":1}},"required":["op","conditions"]},"CommerceEventTriggerFilterLogicalOperator":{"type":"string","enum":["$and","$or"],"description":"Logical operator used to combine multiple filter conditions."},"AgentCollaborations":{"type":"array","description":"List of agent collaborations which allows an agent to hand off its task to other agents. Collaborations remain in the caller's session and do not enable memory by themselves.","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"},{"$ref":"#/components/schemas/TeamsNativeToolResponse"}]}},"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","teams"],"description":"Type of the native tool. Possible values:\n* `slack`\n* `rag_custom`\n* `rag_emporix`\n* `teams`"},"SlackNativeToolConfigResponse":{"type":"object","description":"Configuration of a Slack native tool instance.","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."},"defaultInboundAgentId":{"type":"string","description":"Agent ID that handles inbound Slack replies when no conversation-specific routing context exists yet."},"allowedOperations":{"type":"array","items":{"$ref":"#/components/schemas/SlackAllowedOperations"},"description":"Operations the tool instance exposes to assigned agents. At least one value is required when the tool is enabled."}},"required":["teamId"]},"SlackAllowedOperations":{"type":"string","enum":["sendMessage","createChannel","inviteParticipants","collaborateOnChannel"],"description":"Slack native tool operation identifier."},"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-30T13: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-30T13: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/IdResponse"},{"$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."},"IdResponse":{"type":"object","properties":{"id":{"type":"string","description":"Identifier of the resource."}}},"ExpandedTokenResponse":{"allOf":[{"$ref":"#/components/schemas/IdResponse"},{"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":{"type":"string","description":"Type of the entity which is stored in the given collection. Supported predefined types: [ORDER, PRODUCT] and custom entity types."},"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"]}},"filterFields":{"type":"array","description":"This field specifies the fields of the given entityType that are used for filtering the data before performing actual search.","items":{"type":"object","properties":{"description":{"type":"string","description":"It should contain the description of the field, so LLM is able to know when to use this field in order to filter the data. For enums, possible values should be specified here."},"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"]},"TeamsNativeToolResponse":{"allOf":[{"$ref":"#/components/schemas/BaseNativeTool"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the tool."},"type":{"description":"For TeamsNativeTool it has to be set to `teams`."},"config":{"$ref":"#/components/schemas/TeamsNativeToolConfigResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"TeamsNativeToolConfigResponse":{"type":"object","description":"Configuration of an MS Teams native tool instance.","properties":{"teamId":{"type":"string","description":"Microsoft Teams team ID the tool is bound to."},"tenantId":{"type":"string","description":"Customer Azure AD tenant ID for the Teams workspace."},"defaultInboundAgentId":{"type":"string","description":"Agent ID that handles inbound Teams replies when no conversation-specific owner is set."},"allowedOperations":{"type":"array","items":{"$ref":"#/components/schemas/TeamsAllowedOperations"},"description":"Operations the tool instance exposes to assigned agents. At least one value is required when the tool is enabled."}},"required":["teamId"]},"TeamsAllowedOperations":{"type":"string","enum":["sendMessage","createChat","createChannel","inviteParticipants","collaborateOnChannel","collaborateOnChat"],"description":"MS Teams native tool operation identifier."},"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."},"additionalParams":{"type":"object","additionalProperties":true,"description":"Optional JSON object of extra model parameters. Use it to pass provider-specific options, for example reasoning settings.\n"}},"required":["model"]},"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"]},"baseProvider":{"type":"string","description":"Optional. Indicates which cloud LLM provider API the self-hosted endpoint is compatible with (OPENAI, GOOGLE, or ANTHROPIC). Applies when provider is self_hosted_ollama or self_hosted_vllm. Used to select the correct request/response conventions for that backend. Ignored for non–self-hosted providers.","enum":["ANTHROPIC","GOOGLE","OPENAI"]}},"required":["provider"]}]},"SelfHostedParamsResponse":{"allOf":[{"$ref":"#/components/schemas/SelfHostedParams"},{"type":"object","properties":{"authorizationHeaderToken":{"$ref":"#/components/schemas/ExpandableTokenResponse"},"oauth":{"$ref":"#/components/schemas/ExpandableOAuthResponse"}}}]},"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`."},"fileProcessingConfig":{"$ref":"#/components/schemas/FileProcessingConfig"}},"required":["url"]},"FileProcessingConfig":{"description":"Optional additional config for file processing (preview).\n\n**The `fileProcessingConfig` field is in preview mode** - some of the features may not be fully operational yet.","type":"object","properties":{"useResponsesApi":{"type":"boolean","description":"When true, file processing uses the Responses API on the self-hosted LLM."},"extraModelKey":{"type":"string","description":"Optional extra model identifier used for file processing."}}},"ExpandableOAuthResponse":{"oneOf":[{"$ref":"#/components/schemas/IdResponse"},{"$ref":"#/components/schemas/OAuthResponse"}],"description":"The full response representing OAuth. If the `expand=oauth` is **not** used, then only `id` field is returned, otherwise all fields are returned."},"OAuthResponse":{"allOf":[{"$ref":"#/components/schemas/OAuth"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the entity."},"clientSecretToken":{"$ref":"#/components/schemas/ExpandableTokenResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"OAuth":{"type":"object","description":"OAuth 2.0 client-credentials settings for authenticating with a self-hosted LLM backend.","properties":{"url":{"type":"string","format":"uri","description":"Token endpoint URL of the OAuth 2.0 authorization server used to request an access token."},"clientId":{"type":"string","description":"OAuth 2.0 client identifier registered with the authorization server."},"grantType":{"type":"string","description":"OAuth 2.0 grant type used to obtain an access token. Currently only `client_credentials` is supported.","enum":["client_credentials"]},"scope":{"type":"string","description":"Optional space-separated list of scopes to request for the access token."},"enabled":{"type":"boolean","description":"Indicates whether the OAuth configuration is enabled."}},"required":["url","clientId","grantType"]},"AgentMcpServersResponse":{"type":"array","description":"List of MCP servers which agents should have access to.","items":{"$ref":"#/components/schemas/AgentMcpServerResponse"}},"AgentMcpServerResponse":{"type":"object","required":["type"],"properties":{"type":{"$ref":"#/components/schemas/McpServerType"},"mcpServer":{"allOf":[{"$ref":"#/components/schemas/McpServerResponse"},{"description":"Present for `custom` and `dynamic` attachments. If `expand=mcpServer` is **not** used, then only the `id` field is returned, otherwise all fields are returned."}]},"domain":{"enum":["customer","extensibility","order","product","frontend"],"description":"Present for `predefined` attachments."},"tools":{"type":"array","description":"Tool-name allow-list. Present for `predefined` attachments and for `dynamic` attachments when a subset is configured. Omitted on `dynamic` means all enabled tools on the MCP server.","items":{"type":"string"}}}},"McpServerType":{"type":"string","enum":["custom","predefined","dynamic"],"description":"Type of the MCP server attachment on an agent. The `custom` type references a tenant-managed MCP server with a URL. The `predefined` type references an Emporix domain MCP server. The `dynamic` type references a tenant-managed dynamic MCP server and may include an optional tool-name allow-list."},"McpServerResponse":{"oneOf":[{"$ref":"#/components/schemas/CustomMcpServerResponse"},{"$ref":"#/components/schemas/DynamicMcpServerResponse"}]},"CustomMcpServerResponse":{"allOf":[{"$ref":"#/components/schemas/BaseManagedMcpServer"},{"type":"object","description":"An object representing customer's own implementation of the MCP server.","properties":{"id":{"type":"string","description":"Unique identifier of the MCP server."},"type":{"allOf":[{"$ref":"#/components/schemas/ManagedMcpServerType"}],"description":"Type of the managed MCP server resource."},"config":{"$ref":"#/components/schemas/McpServerConfigResponse"},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"BaseManagedMcpServer":{"type":"object","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 as transport for custom MCP servers."},"ManagedMcpServerType":{"type":"string","enum":["custom","dynamic"],"description":"Type of the managed MCP server resource. Possible values:\n* `custom`\n* `dynamic`\n\n  **The `dynamic` value is in preview mode** - some of the features may not be fully operational yet."},"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"]},"DynamicMcpServerResponse":{"allOf":[{"$ref":"#/components/schemas/BaseManagedMcpServer"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the MCP server."},"type":{"allOf":[{"$ref":"#/components/schemas/ManagedMcpServerType"}],"description":"For dynamic MCP servers it has to be set to `dynamic`."},"tools":{"type":"array","description":"List of tools exposed by this MCP server.\n\n**The `tools` field is in preview mode** - some of the features may not be fully operational yet.","items":{"$ref":"#/components/schemas/McpToolResponse"}},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"McpToolResponse":{"type":"object","description":"Tool definition for a dynamic MCP server.\n\n**Dynamic MCP tools are in preview mode** - some of the features may not be fully operational yet.","properties":{"name":{"type":"string","description":"Unique name of the tool. Contains only letters, numbers, and underscores."},"description":{"type":"string","description":"Human-readable description of the tool."},"prompt":{"type":"string","description":"Prompt that defines when and why the agent should call this tool."},"enabled":{"type":"boolean","description":"An indicator whether the tool is enabled."},"config":{"$ref":"#/components/schemas/McpToolConfigResponse"}}},"McpToolConfigResponse":{"type":"object","properties":{"requiredScopes":{"type":"array","description":"OAuth scopes required to invoke the tool.","items":{"type":"string"}},"inputSchema":{"type":"string","description":"JSON Schema document describing the tool input, provided as a JSON string."},"invocation":{"$ref":"#/components/schemas/McpToolInvocationResponse"}}},"McpToolInvocationResponse":{"type":"object","properties":{"functionId":{"type":"string","description":"Identifier of the Automation function to invoke when the tool is called."},"method":{"$ref":"#/components/schemas/McpToolInvocationMethod"},"argsLocation":{"$ref":"#/components/schemas/McpToolInvocationArgsLocation"}}},"McpToolInvocationMethod":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"description":"HTTP method used to invoke the Automation function."},"McpToolInvocationArgsLocation":{"type":"string","enum":["body","query"],"description":"Location of the tool arguments in the HTTP request. Defaults to `body` when omitted."},"HandOff":{"type":"boolean","deprecated":true,"description":"Deprecated. Indicates whether the agent is a hand-off agent. This field is no longer used. Clients should ignore it."},"AgentType":{"type":"string","description":"Type of the agent handling the request.","enum":["generic","complaint","anti_fraud"]},"AgentMetadataResponse":{"allOf":[{"$ref":"#/components/schemas/MetadataResponse"},{"type":"object","properties":{"modifiedBy":{"$ref":"#/components/schemas/ModifiedBy"},"changeNote":{"type":"string","description":"Note stored for this live version."}}}]},"ModifiedBy":{"type":"object","description":"Who last changed the agent.","required":["type"],"properties":{"type":{"type":"string","enum":["CUSTOMER","EMPLOYEE","EXTERNAL","SYSTEM"],"description":"Identity recorded for the change. `EXTERNAL` is assigned when the request authenticates with an API token. `SYSTEM` is used for automatic updates.\n"},"id":{"type":"string","description":"Identifier of the customer or employee. Omitted for `EXTERNAL` and `SYSTEM`. `id` is the `Hybris-User-Id` header value when `CUSTOMER` or `EMPLOYEE`."},"firstName":{"type":"string","description":"First name of the customer or employee."},"lastName":{"type":"string","description":"Last name of the customer or employee."}}},"AgentVersion":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentRequestAndResponse"},{"type":"object","properties":{"templatePrompt":{"type":"string","description":"Prompt inherited from the template at the time of this version."},"nativeTools":{"$ref":"#/components/schemas/NativeToolsResponse"},"llmConfig":{"oneOf":[{"$ref":"#/components/schemas/EmporixLlm"},{"$ref":"#/components/schemas/ApiKeyLlmResponse"},{"$ref":"#/components/schemas/SelfHostedLlmResponse"}]},"mcpServers":{"$ref":"#/components/schemas/AgentMcpServersResponse"},"metadata":{"$ref":"#/components/schemas/AgentVersionMetadata"}},"required":["metadata"]}]},"AgentVersionMetadata":{"type":"object","required":["version"],"properties":{"version":{"type":"integer","minimum":1,"description":"Version number of this archived snapshot."},"modifiedAt":{"type":"string","description":"Date and time when this version was stored. The value is an ISO-8601 instant. For example: `2022-04-30T13:18:02.379Z`"},"modifiedBy":{"$ref":"#/components/schemas/ModifiedBy"},"changeNote":{"type":"string","description":"Note stored with this snapshot."}}},"ErrorMessage":{"type":"object","properties":{"code":{"type":"integer"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}},"description":""},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}},"responses":{"400_resp_common":{"description":"The request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"403_resp_common":{"description":"Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"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"},{"$ref":"#/components/parameters/agentVersion"},{"$ref":"#/components/parameters/allVersions"}],"summary":"Retrieving agent by ID","operationId":"GET-ai-retrieve-agent","responses":{"200":{"description":"A single agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"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":"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.\
> A successful update increments \`metadata.version\` and stores the previous configuration. A request that sends a stale \`metadata.version\` returns \`409\`.

```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.agentexecution_manage":"Needed to execute agentic chat.","ai.agentexecution_manage_own":"Needed to execute agentic chat by customers.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"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/NativeToolReferenceRequest"},"description":"Native tools assigned to the agent, optionally with per-agent `allowedOperations` overrides."},"llmConfig":{"oneOf":[{"$ref":"#/components/schemas/EmporixLlm"},{"$ref":"#/components/schemas/ApiKeyLlmRequest"},{"$ref":"#/components/schemas/SelfHostedLlmRequest"}]},"mcpServers":{"$ref":"#/components/schemas/AgentMcpServersRequest"},"metadata":{"allOf":[{"$ref":"#/components/schemas/MetadataRequest"},{"type":"object","properties":{"changeNote":{"type":"string","description":"Optional note stored on this version. A blank value clears the live note. The next successful update archives the note with this version."}}}]}},"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 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.","default":false}},"required":["userPrompt","triggers"]}]},"BaseForAgentAndTemplate":{"allOf":[{"$ref":"#/components/schemas/BaseForAgentAndTemplateAndHandOff"},{"type":"object","properties":{"requiredScopes":{"type":"array","description":"Defines which caller types are allowed to execute the agent.\nAuthorization is evaluated with OR semantics: access is granted if the caller\nmatches at least one configured value.\nIf this field is missing or empty, no scope-based restriction is applied.\n\nMatching rules:\n- anonymous: always grants access.\n- customer: requires scope `ai.agentexecution_manage_own`.\n- employee: requires scope `ai.agentexecution_manage`.\n- integration: requires scope `ai.agentexecution_manage`.\n\nIf no configured value matches, request is rejected with 403 Forbidden.\n","items":{"type":"string","enum":["anonymous","customer","employee","integration"]}},"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."}},"outputFormat":{"type":"string","description":"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.\n"},"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."},"filter":{"$ref":"#/components/schemas/CommerceEventTriggerFilter"},"eventScopes":{"type":"array","description":"Optional IAM scopes used to obtain an Emporix token when the agent runs from a Commerce Event. When omitted or empty, the agent does not receive `emporix-token`. Each value must be a scope the caller is allowed to grant.","items":{"type":"string"},"uniqueItems":true}},"required":["events"]}},"required":["type","config"]}]},"TriggerType":{"type":"string","enum":["endpoint","slack","teams"],"description":"Type of the trigger. When `slack` or `teams` is selected, the agent must have exactly one matching enabled Slack or Teams native tool assigned."},"CommerceEventsTriggerType":{"type":"string","enum":["commerce_events"],"description":"Type of the trigger."},"CommerceEventTriggerFilter":{"oneOf":[{"$ref":"#/components/schemas/CommerceEventTriggerLeafFilter"},{"$ref":"#/components/schemas/CommerceEventTriggerCompoundFilter"}],"description":"Optional filter expression applied to commerce event payloads. When set, the agent is triggered only if the event payload matches the filter."},"CommerceEventTriggerLeafFilter":{"description":"Filter condition applied to a single field in the commerce event payload.","oneOf":[{"$ref":"#/components/schemas/CommerceEventTriggerLeafFilterNoRight"},{"$ref":"#/components/schemas/CommerceEventTriggerLeafFilterScalarRight"},{"$ref":"#/components/schemas/CommerceEventTriggerLeafFilterArrayRight"}]},"CommerceEventTriggerLeafFilterNoRight":{"type":"object","description":"Filter condition for unary operators that do not accept `right`.","properties":{"left":{"type":"string","description":"Dot-notation path to a field in the commerce event payload."},"op":{"type":"string","enum":["$exists","$notExists","$isEmpty","$notEmpty"]}},"required":["left","op"],"additionalProperties":false},"CommerceEventTriggerLeafFilterScalarRight":{"type":"object","description":"Filter condition for scalar comparison operators.","properties":{"left":{"type":"string","description":"Dot-notation path to a field in the commerce event payload."},"op":{"type":"string","enum":["$eq","$ne"]},"right":{"$ref":"#/components/schemas/CommerceEventTriggerFilterScalarValue"}},"required":["left","op","right"],"additionalProperties":false},"CommerceEventTriggerFilterScalarValue":{"description":"Scalar value used in commerce event filter comparisons.","oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"CommerceEventTriggerLeafFilterArrayRight":{"type":"object","description":"Filter condition for array membership operators.","properties":{"left":{"type":"string","description":"Dot-notation path to a field in the commerce event payload."},"op":{"type":"string","enum":["$in","$notIn"]},"right":{"$ref":"#/components/schemas/CommerceEventTriggerFilterScalarArrayValue"}},"required":["left","op","right"],"additionalProperties":false},"CommerceEventTriggerFilterScalarArrayValue":{"type":"array","description":"Array value used by list-based operators in commerce event filters.","items":{"$ref":"#/components/schemas/CommerceEventTriggerFilterScalarValue"},"minItems":1},"CommerceEventTriggerCompoundFilter":{"type":"object","description":"Filter that combines multiple conditions using logical operators.","properties":{"op":{"$ref":"#/components/schemas/CommerceEventTriggerFilterLogicalOperator"},"conditions":{"type":"array","description":"Nested filter conditions combined by the logical operator.","items":{"$ref":"#/components/schemas/CommerceEventTriggerFilter"},"minItems":1}},"required":["op","conditions"]},"CommerceEventTriggerFilterLogicalOperator":{"type":"string","enum":["$and","$or"],"description":"Logical operator used to combine multiple filter conditions."},"AgentCollaborations":{"type":"array","description":"List of agent collaborations which allows an agent to hand off its task to other agents. Collaborations remain in the caller's session and do not enable memory by themselves.","items":{"type":"object","properties":{"agentId":{"type":"string","description":"Identifier of the agent."},"description":{"type":"string","description":"Description of the agent collaboration."}}}},"NativeToolReferenceRequest":{"type":"object","description":"Reference to a native tool assigned to an agent.","properties":{"id":{"type":"string","description":"Identifier of the native tool."},"allowedOperations":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/TeamsAllowedOperations"},{"$ref":"#/components/schemas/SlackAllowedOperations"}]},"description":"Optional per-agent override of allowed native tool operations. When omitted, the tool instance defaults apply. Supported for MS Teams and Slack."}},"required":["id"]},"TeamsAllowedOperations":{"type":"string","enum":["sendMessage","createChat","createChannel","inviteParticipants","collaborateOnChannel","collaborateOnChat"],"description":"MS Teams native tool operation identifier."},"SlackAllowedOperations":{"type":"string","enum":["sendMessage","createChannel","inviteParticipants","collaborateOnChannel"],"description":"Slack native tool operation identifier."},"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."},"additionalParams":{"type":"object","additionalProperties":true,"description":"Optional JSON object of extra model parameters. Use it to pass provider-specific options, for example reasoning settings.\n"}},"required":["model"]},"ApiKeyLlmRequest":{"allOf":[{"$ref":"#/components/schemas/ApiKeyLlm"},{"type":"object","properties":{"token":{"$ref":"#/components/schemas/IdWrapperRequest"}},"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"]},"IdWrapperRequest":{"type":"object","properties":{"id":{"type":"string"}},"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"]},"baseProvider":{"type":"string","description":"Optional. Indicates which cloud LLM provider API the self-hosted endpoint is compatible with (OPENAI, GOOGLE, or ANTHROPIC). Applies when provider is self_hosted_ollama or self_hosted_vllm. Used to select the correct request/response conventions for that backend. Ignored for non–self-hosted providers.","enum":["ANTHROPIC","GOOGLE","OPENAI"]}},"required":["provider"]}]},"SelfHostedParamsRequest":{"allOf":[{"$ref":"#/components/schemas/SelfHostedParams"},{"type":"object"},{"properties":{"authorizationHeaderToken":{"$ref":"#/components/schemas/IdWrapperRequest"},"oauth":{"$ref":"#/components/schemas/IdWrapperRequest"}}}]},"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`."},"fileProcessingConfig":{"$ref":"#/components/schemas/FileProcessingConfig"}},"required":["url"]},"FileProcessingConfig":{"description":"Optional additional config for file processing (preview).\n\n**The `fileProcessingConfig` field is in preview mode** - some of the features may not be fully operational yet.","type":"object","properties":{"useResponsesApi":{"type":"boolean","description":"When true, file processing uses the Responses API on the self-hosted LLM."},"extraModelKey":{"type":"string","description":"Optional extra model identifier used for file processing."}}},"AgentMcpServersRequest":{"type":"array","description":"List of MCP servers which agents should have access to.","items":{"oneOf":[{"$ref":"#/components/schemas/CustomAgentMcpServerRequest"},{"$ref":"#/components/schemas/DynamicAgentMcpServerRequest"},{"$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","dynamic"],"description":"Type of the MCP server attachment on an agent. The `custom` type references a tenant-managed MCP server with a URL. The `predefined` type references an Emporix domain MCP server. The `dynamic` type references a tenant-managed dynamic MCP server and may include an optional tool-name allow-list."},"DynamicAgentMcpServerRequest":{"allOf":[{"$ref":"#/components/schemas/BaseAgentMcpServer"},{"type":"object","properties":{"type":{"description":"For a dynamic MCP server attachment it has to be set to `dynamic`."},"mcpServer":{"type":"object","properties":{"id":{"type":"string","description":"ID of the dynamic MCP server."}},"required":["id"]},"tools":{"type":"array","description":"Optional allow-list of tool names from the dynamic MCP server.","items":{"type":"string"}}},"required":["mcpServer"]}]},"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.\nA successful update increments `metadata.version` and stores the previous configuration. A request that sends a stale `metadata.version` returns `409`.","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.agentexecution_manage":"Needed to execute agentic chat.","ai.agentexecution_manage_own":"Needed to execute agentic chat by customers.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"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)\
> A successful update increments \`metadata.version\` and stores the previous configuration. A request that sends a stale \`metadata.version\` returns \`409\`.

```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.agentexecution_manage":"Needed to execute agentic chat.","ai.agentexecution_manage_own":"Needed to execute agentic chat by customers.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"responses":{"400_resp_common":{"description":"The request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"403_resp_common":{"description":"Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"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"}}}}},"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"},"409":{"$ref":"#/components/responses/409_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)\nA successful update increments `metadata.version` and stores the previous configuration. A request that sends a stale `metadata.version` returns `409`.","requestBody":{"$ref":"#/components/requestBodies/agentPatchBody"},"tags":["Agent"]}}}}
```


---

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

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

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

```
GET https://developer.emporix.io/api-references/readme/api-reference/agent.md?ask=<question>&goal=<user_goal>
```

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

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

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