From efbc9ce1e61a9a1c849d3f77446b0ecbd0486b9a Mon Sep 17 00:00:00 2001 From: Mathias Geat Date: Fri, 24 Oct 2025 13:06:42 +0200 Subject: [PATCH 1/3] docs(agentic-ai): document AI Agent error codes --- .../agentic-ai-aiagent-subprocess.md | 2 +- .../agentic-ai-aiagent-task.md | 2 +- .../aiagent/configuration/_error-codes-task.md | 7 +++++++ .../aiagent/configuration/_error-handling.md | 15 +++++++++++++++ 4 files changed, 24 insertions(+), 2 deletions(-) create mode 100644 docs/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-codes-task.md diff --git a/docs/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-subprocess.md b/docs/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-subprocess.md index 21d1498b8c6..ca8408974c5 100644 --- a/docs/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-subprocess.md +++ b/docs/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-subprocess.md @@ -57,6 +57,6 @@ See [event handling](#configuration-event-handling) for more information. - + diff --git a/docs/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-task.md b/docs/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-task.md index a00cacaf9f4..3efdb3e69bb 100644 --- a/docs/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-task.md +++ b/docs/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-task.md @@ -41,7 +41,7 @@ Implement an AI agent using an AI Agent connector applied to a service task, pai - + diff --git a/docs/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-codes-task.md b/docs/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-codes-task.md new file mode 100644 index 00000000000..78d679515f9 --- /dev/null +++ b/docs/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-codes-task.md @@ -0,0 +1,7 @@ +The AI Agent Task emits the following error codes when generating the tools schema from the process definition XML: + +| Error code | Description | +| :----------------------------------- | :------------------------------------------------------------------------------------------------------- | +| `AD_HOC_SUB_PROCESS_XML_FETCH_ERROR` | The process definition XML could not be fetched. | +| `AD_HOC_SUB_PROCESS_NOT_FOUND` | The ad-hoc sub-process with the configured ID could not be found in the process definition XML. | +| `AD_HOC_TOOL_DEFINITION_INVALID` | The ad-hoc sub-process contains invalid tool definitions which can't be transformed into a tools schema. | diff --git a/docs/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-handling.md b/docs/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-handling.md index aa907568a6c..538901240f0 100644 --- a/docs/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-handling.md +++ b/docs/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-handling.md @@ -1,3 +1,5 @@ +import ConfigurationErrorCodesTask from './\_error-codes-task.md'; + ### Error handling If an error occurs, the AI Agent connector throws an error and includes the error response in the error variable in Operate. @@ -5,3 +7,16 @@ If an error occurs, the AI Agent connector throws an error and includes the erro | Field | Required | Description | | :--------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Error expression | No | You can handle an AI Agent connector error using an Error Boundary Event and [error expressions](/components/connectors/use-connectors/index.md#error-expression). | + +In the error expression, you can handle the following error codes emitted by the AI Agent connector to react on specific situations. For example, you can map a specific error code to a BPMN error and model +your process accordingly. + +| Error code | Description | +| :-------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | +| `FAILED_MODEL_CALL` | The call to the LLM API failed, for example due to misconfiguration or wrong credentials. The error message contains additional details. | +| `FAILED_TO_PARSE_RESPONSE_CONTENT` | The AI Agent was configured to parse the LLM response as JSON, but the parsing failed. | +| `MAXIMUM_NUMBER_OF_MODEL_CALLS_REACHED` | The AI Agent reached the maximum number of configured model calls. | +| `NO_USER_MESSAGE_CONTENT` | Indicates that no user messages content - either coming from a user prompt or a document - was provided to the agent. | +| `TOOL_CALL_RESULTS_ON_EMPTY_CONTEXT` | Tool call results were passed to the AI Agent despite the context being empty. This typically indicates misconfiguration of the agent context. | + +{props.type === "task" && } From 127ae5cd7df79d02089aea45b71dab795c1a6534 Mon Sep 17 00:00:00 2001 From: Mathias Geat Date: Fri, 24 Oct 2025 13:09:09 +0200 Subject: [PATCH 2/3] docs(agentic-ai): document AI Agent error codes (8.8) Difference: no FAILED_MODEL_CALL error code --- .../agentic-ai-aiagent-subprocess.md | 2 +- .../agentic-ai-aiagent-task.md | 2 +- .../aiagent/configuration/_error-codes-task.md | 7 +++++++ .../aiagent/configuration/_error-handling.md | 14 ++++++++++++++ 4 files changed, 23 insertions(+), 2 deletions(-) create mode 100644 versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-codes-task.md diff --git a/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-subprocess.md b/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-subprocess.md index 21d1498b8c6..ca8408974c5 100644 --- a/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-subprocess.md +++ b/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-subprocess.md @@ -57,6 +57,6 @@ See [event handling](#configuration-event-handling) for more information. - + diff --git a/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-task.md b/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-task.md index a00cacaf9f4..3efdb3e69bb 100644 --- a/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-task.md +++ b/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-task.md @@ -41,7 +41,7 @@ Implement an AI agent using an AI Agent connector applied to a service task, pai - + diff --git a/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-codes-task.md b/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-codes-task.md new file mode 100644 index 00000000000..78d679515f9 --- /dev/null +++ b/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-codes-task.md @@ -0,0 +1,7 @@ +The AI Agent Task emits the following error codes when generating the tools schema from the process definition XML: + +| Error code | Description | +| :----------------------------------- | :------------------------------------------------------------------------------------------------------- | +| `AD_HOC_SUB_PROCESS_XML_FETCH_ERROR` | The process definition XML could not be fetched. | +| `AD_HOC_SUB_PROCESS_NOT_FOUND` | The ad-hoc sub-process with the configured ID could not be found in the process definition XML. | +| `AD_HOC_TOOL_DEFINITION_INVALID` | The ad-hoc sub-process contains invalid tool definitions which can't be transformed into a tools schema. | diff --git a/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-handling.md b/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-handling.md index aa907568a6c..fd5e272ce91 100644 --- a/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-handling.md +++ b/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-handling.md @@ -1,3 +1,5 @@ +import ConfigurationErrorCodesTask from './\_error-codes-task.md'; + ### Error handling If an error occurs, the AI Agent connector throws an error and includes the error response in the error variable in Operate. @@ -5,3 +7,15 @@ If an error occurs, the AI Agent connector throws an error and includes the erro | Field | Required | Description | | :--------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Error expression | No | You can handle an AI Agent connector error using an Error Boundary Event and [error expressions](/components/connectors/use-connectors/index.md#error-expression). | + +In the error expression, you can handle the following error codes emitted by the AI Agent connector to react on specific situations. For example, you can map a specific error code to a BPMN error and model +your process accordingly. + +| Error code | Description | +| :-------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | +| `FAILED_TO_PARSE_RESPONSE_CONTENT` | The AI Agent was configured to parse the LLM response as JSON, but the parsing failed. | +| `MAXIMUM_NUMBER_OF_MODEL_CALLS_REACHED` | The AI Agent reached the maximum number of configured model calls. | +| `NO_USER_MESSAGE_CONTENT` | Indicates that no user messages content - either coming from a user prompt or a document - was provided to the agent. | +| `TOOL_CALL_RESULTS_ON_EMPTY_CONTEXT` | Tool call results were passed to the AI Agent despite the context being empty. This typically indicates misconfiguration of the agent context. | + +{props.type === "task" && } From 7c40f6679a2838a8bacce6add93cabb9a02fee7c Mon Sep 17 00:00:00 2001 From: Mathias Geat Date: Sun, 2 Nov 2025 14:32:53 +0100 Subject: [PATCH 3/3] docs(agentic-ai): Apply review suggestions Co-authored-by: Angel Fernandez <103958447+afgambin@users.noreply.github.com> --- .../agentic-ai/aiagent/configuration/_error-codes-task.md | 4 ++-- .../agentic-ai/aiagent/configuration/_error-handling.md | 6 +++--- .../agentic-ai/aiagent/configuration/_error-codes-task.md | 4 ++-- .../agentic-ai/aiagent/configuration/_error-handling.md | 6 +++--- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-codes-task.md b/docs/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-codes-task.md index 78d679515f9..8e74f8c3adb 100644 --- a/docs/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-codes-task.md +++ b/docs/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-codes-task.md @@ -1,7 +1,7 @@ -The AI Agent Task emits the following error codes when generating the tools schema from the process definition XML: +The AI Agent Task generates the following error codes when creating the tool schema from the process definition XML: | Error code | Description | | :----------------------------------- | :------------------------------------------------------------------------------------------------------- | | `AD_HOC_SUB_PROCESS_XML_FETCH_ERROR` | The process definition XML could not be fetched. | | `AD_HOC_SUB_PROCESS_NOT_FOUND` | The ad-hoc sub-process with the configured ID could not be found in the process definition XML. | -| `AD_HOC_TOOL_DEFINITION_INVALID` | The ad-hoc sub-process contains invalid tool definitions which can't be transformed into a tools schema. | +| `AD_HOC_TOOL_DEFINITION_INVALID` | The ad-hoc sub-process contains invalid tool definitions which can't be transformed into a tool schema. | diff --git a/docs/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-handling.md b/docs/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-handling.md index 538901240f0..f25e7c50fd3 100644 --- a/docs/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-handling.md +++ b/docs/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-handling.md @@ -8,7 +8,7 @@ If an error occurs, the AI Agent connector throws an error and includes the erro | :--------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Error expression | No | You can handle an AI Agent connector error using an Error Boundary Event and [error expressions](/components/connectors/use-connectors/index.md#error-expression). | -In the error expression, you can handle the following error codes emitted by the AI Agent connector to react on specific situations. For example, you can map a specific error code to a BPMN error and model +In the error expression, you can handle the following error codes emitted by the AI Agent connector to respond to specific situations. For example, you can map a specific error code to a BPMN error and model your process accordingly. | Error code | Description | @@ -16,7 +16,7 @@ your process accordingly. | `FAILED_MODEL_CALL` | The call to the LLM API failed, for example due to misconfiguration or wrong credentials. The error message contains additional details. | | `FAILED_TO_PARSE_RESPONSE_CONTENT` | The AI Agent was configured to parse the LLM response as JSON, but the parsing failed. | | `MAXIMUM_NUMBER_OF_MODEL_CALLS_REACHED` | The AI Agent reached the maximum number of configured model calls. | -| `NO_USER_MESSAGE_CONTENT` | Indicates that no user messages content - either coming from a user prompt or a document - was provided to the agent. | -| `TOOL_CALL_RESULTS_ON_EMPTY_CONTEXT` | Tool call results were passed to the AI Agent despite the context being empty. This typically indicates misconfiguration of the agent context. | +| `NO_USER_MESSAGE_CONTENT` | Indicates that no user message content, either from a user prompt or a document, was provided to the agent. | +| `TOOL_CALL_RESULTS_ON_EMPTY_CONTEXT` | Tool call results were passed to the AI Agent despite the context being empty, which typically indicates a misconfiguration of the agent context. | {props.type === "task" && } diff --git a/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-codes-task.md b/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-codes-task.md index 78d679515f9..8e74f8c3adb 100644 --- a/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-codes-task.md +++ b/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-codes-task.md @@ -1,7 +1,7 @@ -The AI Agent Task emits the following error codes when generating the tools schema from the process definition XML: +The AI Agent Task generates the following error codes when creating the tool schema from the process definition XML: | Error code | Description | | :----------------------------------- | :------------------------------------------------------------------------------------------------------- | | `AD_HOC_SUB_PROCESS_XML_FETCH_ERROR` | The process definition XML could not be fetched. | | `AD_HOC_SUB_PROCESS_NOT_FOUND` | The ad-hoc sub-process with the configured ID could not be found in the process definition XML. | -| `AD_HOC_TOOL_DEFINITION_INVALID` | The ad-hoc sub-process contains invalid tool definitions which can't be transformed into a tools schema. | +| `AD_HOC_TOOL_DEFINITION_INVALID` | The ad-hoc sub-process contains invalid tool definitions which can't be transformed into a tool schema. | diff --git a/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-handling.md b/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-handling.md index fd5e272ce91..a918bf4390c 100644 --- a/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-handling.md +++ b/versioned_docs/version-8.8/components/connectors/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-handling.md @@ -8,14 +8,14 @@ If an error occurs, the AI Agent connector throws an error and includes the erro | :--------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Error expression | No | You can handle an AI Agent connector error using an Error Boundary Event and [error expressions](/components/connectors/use-connectors/index.md#error-expression). | -In the error expression, you can handle the following error codes emitted by the AI Agent connector to react on specific situations. For example, you can map a specific error code to a BPMN error and model +In the error expression, you can handle the following error codes emitted by the AI Agent connector to respond to specific situations. For example, you can map a specific error code to a BPMN error and model your process accordingly. | Error code | Description | | :-------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | | `FAILED_TO_PARSE_RESPONSE_CONTENT` | The AI Agent was configured to parse the LLM response as JSON, but the parsing failed. | | `MAXIMUM_NUMBER_OF_MODEL_CALLS_REACHED` | The AI Agent reached the maximum number of configured model calls. | -| `NO_USER_MESSAGE_CONTENT` | Indicates that no user messages content - either coming from a user prompt or a document - was provided to the agent. | -| `TOOL_CALL_RESULTS_ON_EMPTY_CONTEXT` | Tool call results were passed to the AI Agent despite the context being empty. This typically indicates misconfiguration of the agent context. | +| `NO_USER_MESSAGE_CONTENT` | Indicates that no user message content, either from a user prompt or a document, was provided to the agent. | +| `TOOL_CALL_RESULTS_ON_EMPTY_CONTEXT` | Tool call results were passed to the AI Agent despite the context being empty, which typically indicates a misconfiguration of the agent context. | {props.type === "task" && }