AI Agent Process connector

Implement an AI agent using an ad-hoc sub-process with an applied AI Agent connector template.

About this implementation

This connector implementation creates an implicit feedback loop for tool calls and agent responses, using the job worker implementation type of an ad-hoc sub-process.

info

• For more information and usage examples, see AI Agent Process.
• The example integration outlines how to model an agentic AI process using the AI Agent Process implementation.

Event handling

With an AI Agent Process, an event handled as part of an event subprocess will directly trigger an execution of the underlying job worker which can either interrupt ongoing tool calls or wait for all tool calls to complete before handling the event.

• To provide additional data to the LLM from a handled event, create a toolCallResult variable from the event handling flow.
• The content of this variable is added to the LLM API request as a user message following any tool call results.

info

See event handling for more information.

Configuration

Model Provider

Select and configure authentication for the LLM model Provider you want to use, from the following supported providers:

• Anthropic (Claude models)
• Amazon Bedrock
• Azure OpenAI
• Google Vertex AI
• OpenAI
• OpenAI-compatible

note

• Different setup/authentication fields are shown depending on the provider you select.
• Use connector secrets to store credentials and avoid exposing sensitive information directly from the process.

Anthropic

Select this option to use an Anthropic Claude LLM model (uses the Anthropic Messages API).

Field	Required	Description
Anthropic API key	Yes	Your Anthropic account API key for authorization to the Anthropic Messages API.

info

For more information about Anthropic Claude LLM models, refer to the Claude models overview.

Bedrock

Select this option to use a model provided by the Amazon Bedrock service, using the Converse API.

Field	Required	Description
Region	Yes	The AWS region. Example: us-east-1
Authentication	Yes	Select the authentication type you want to use to authenticate the connector with AWS. To learn more about configuring AWS authentication, see Amazon Bedrock connector authentication.

Model availability depends on the region and model you use. You might need to request a model is made available for your account. To learn more about configuring access to foundation models, refer to access to Amazon Bedrock foundation models.

info

For a list of Amazon Bedrock LLM models, refer to supported foundation models in Amazon Bedrock.

Azure OpenAI

Select this option to use Azure OpenAI models.

Field	Required	Description
Endpoint	Yes	The Azure OpenAI endpoint URL. Example: https://<your-resource-name>.openai.azure.com/
Authentication	Yes	Select the authentication type you want to use to authenticate the connector with Azure OpenAI.

Two authentication methods are currently supported:

• API key: Authenticate using an Azure OpenAI API key, available in the Azure AI Foundry portal.

• Client credentials: Authenticate using a client ID and secret. This method requires registering an application in Microsoft Entra ID. Provide the following fields:

  • Client ID – The Microsoft Entra application ID.
  • Client secret – The application’s client secret.
  • Tenant ID – The Microsoft Entra tenant ID.
  • Authority host – (Optional) The authority host URL. Defaults to https://login.microsoftonline.com/. This can also be an OAuth 2.0 token endpoint.

note

To use an Azure OpenAI model, you must first deploy it in the Azure AI Foundry portal. For details, see Deploy a model in Azure OpenAI. The deployment ID must then be provided in the Model field.

Google Vertex AI

Select this option to use Google Vertex AI models.

Field	Required	Description
Project ID	Yes	The Google Cloud project ID.
Region	Yes	The region where AI inference should take place.
Authentication	Yes	Select the authentication type to use for connecting to Google Cloud.

Two authentication methods are currently supported:

• Service Account Credentials: Authenticate using a service account key in JSON format.
• Application Default Credentials (ADC): Authenticate using the default credentials available in your environment.
  This method is only supported in Self-Managed or hybrid environments.
  To set up ADC in a local development environment, follow the instructions here.

info

For more information about Google Vertex AI models, see the Vertex AI documentation.

OpenAI

Select this option to use the OpenAI Chat Completion API.

Field	Required	Description
OpenAI API key	Yes	Your OpenAI account API key for authorization.
Organization ID	No	For members of multiple organizations. If you belong to multiple organizations, specify the organization ID to use for API requests with this connector.
Project ID	No	If you access projects through a legacy user API key, specify the project ID to use for API requests with this connector.

info

To learn more about authentication to the OpenAPI API, refer to OpenAPI platform API reference.

OpenAI-compatible

Select this option to use an LLM provider that provides OpenAI-compatible endpoints.

Field	Required	Description
API endpoint	Yes	The base URL of the OpenAI-compatible endpoint. Example value: https://api.your-llm-provider.com/v1
API key	No	The API key for authentication. Leave blank if using HTTP headers for authentication. If an Authorization header is specified in the headers, then the API key is ignored.
Headers	No	Optional HTTP headers to include in the request to the OpenAI-compatible endpoint.

note

A Custom parameters field is available in the model parameters to provide any additional parameters supported by your OpenAI-compatible provider.

Model

Select the model you want to use for the selected provider, and specify any additional model parameters.

Field	Required	Description
Model	Yes	Specify the model ID for the model you want to use. Example: anthropic.claude-3-5-sonnet-20240620-v1:0
Maximum tokens	No	The maximum number of tokens per request to allow in the generated response.
Maximum completion tokens	No	The maximum number of tokens per request to generate before stopping.
Temperature	No	Floating point number, typically between 0 and 1 (0 and 2 for OpenAI). The higher the number, the more randomness will be injected into the response.
top P	No	Floating point number, typically between 0 and 1. Recommended for advanced use cases only (usually you only need to use temperature).
top K	No	Integer greater than 0. Recommended for advanced use cases only (you usually only need to use temperature).

note

• Different model parameter fields are shown depending on the provider/model you select. Additionally, some parameters may be different or have different value ranges (for example, OpenAI Temperature uses a number range between 0 to 2, whereas other models use a range between 0 to 1).
• For more information on each model parameter, refer to the provider documentation links in the element template.
• Parameters that set maximum values (such as maximum tokens) are considered per LLM request, not for the whole conversation. Depending on the provider, the exact meaning of these parameters may vary.

System Prompt

The System Prompt is a crucial part of the AI Agent connector configuration, as it defines the behavior and goal of the agent and instructs the LLM on how to act.

Field	Required	Description
System prompt	Yes	Specify a system prompt to define how the LLM should act. A minimal example system prompt is provided as a starting point for you to customize. You can use FEEL expressions to add dynamic values into the text.

User Prompt

The User Prompt contains the actual request to the LLM model.

Field	Required	Description
User prompt	Yes	This could either contain the initial request or a follow-up request as part of a response interaction feedback loop. The value provided as part of this field is added to the conversation memory and passed to the LLM call. For example, in the example conversation, this would be the messages prefixed with User:. You can use FEEL expressions to add dynamic values into the text.
Documents	No	Add a document references list to allow an AI agent to interact with documents and images. This list is internally resolved and passed to the LLM model if the document type is supported. LLM APIs provide a way to specify the user prompt as a list of content blocks. If document references are passed, they are resolved to a corresponding content block and passed as part of the user message. For examples of how LLM providers accept document content blocks, refer to the Anthropic and OpenAI documentation.

Supported document types

As file type support varies by LLM provider/model, you must test your document use case with the provider you are using.

File type	Supported	Description
Text	Yes	Text files (MIME types matching text/*, application/xml, application/json, or application/yaml) are passed as plain text content blocks.
PDF	Yes	PDF files (MIME types matching application/pdf) are passed as base64 encoded content blocks.
Image	Yes	Image files (MIME types matching image/jpg, image/png, image/gif, or image/webp) are passed as base64 encoded content blocks.
Audio/video/other	No	Audio and video files are not currently supported, and will result in an error if passed. All other unsupported file types not listed here will also result in an error if passed.

info

To learn more about storing, tracking, and managing documents in Camunda 8, see document handling.

Memory

Configure the agent's short-term/conversational memory.

For the AI Agent Process implementation, configuration of the agent context field is only necessary when re-entering the agent as part of a feedback loop outside the agent execution.

Field	Required	Description
Agent context	No	As the process implementation keeps the agent context within the subprocess scope, it is only necessary to configure the agent context when the agent should pick up an existing conversation, for example to model a user feedback loop as used in the quickstart example. Should be used in combination with the Include agent context setting in the response section and be aligned with the used result variable. Example: =agent.context, =anotherAgent.context

Depending on your use case, you can store the conversation memory in different storage backends.

Field	Required	Description
Memory storage type	Yes	Specify how the conversation memory should be stored. In Process (part of agent context): conversation messages will be stored as process variable and be subject to variable size limitations. This is the default value. Camunda Document Storage: messages will be stored as a JSON document in document storage. Custom Implementation (Hybrid/Self-Managed only): a custom storage implementation using a customized connector runtime.
Context window size	No	Specify the maximum number of messages to pass to the LLM on every call. Defaults to 20 if not configured. Configuring this is a trade-off between cost/tokens and the context window supported by the used model. When the conversation exceeds the configured context window size, the oldest messages from past feedback loops are omitted from the model API call first. The system prompt is always kept in the list of messages passed to the LLM.

In-process storage

Messages passed between the AI agent and the model are stored within the agent context variable and directly visible in Operate.

This is suitable for many use cases, but you must be aware of the variable size limitations that limit the amount of data that can be stored in the process variable.

Camunda document storage

Messages passed between the AI agent and the model are not directly available as process variable but reference a JSON document stored in document storage.

As documents are subject to expiration, to avoid losing the conversation history you must be able to predict the expected lifetime of your process, so you can correctly configure the document time-to-live (TTL).

Field	Required	Description
Document TTL	No	Time-to-live (TTL) for documents containing the conversation history. Use this field to set a custom TTL matching your expected process lifetime. The default cluster TTL is used if this value is not configured.
Custom document properties	No	Optional map of properties to store with the document. Use this option to reference custom metadata you might want to use when further processing conversation documents.

Custom implementation

info

This option is only supported if you are using a customized AI Agent connector in a Self-Managed or hybrid setup. See customization for more details.

Field	Required	Description
Implementation type	Yes	The type identifier of your custom storage implementation. See customization for an example.
Parameters	No	Optional map of parameters to be passed to the storage implementation.

Limits

Set limits for the agent interaction to prevent unexpected behavior or unexpected cost due to infinite loops.

Field	Required	Description
Maximum model calls	No	Specify the maximum number of model calls. As a safeguard, this limit defaults to a value of 10 if you do not configure this value.

caution

Despite these limits, you must closely monitor your LLM API usage and cost, and set appropriate limits on the provider side.

Event handling

Configures how the AI Agent process should behave when handling results from an event subprocess.

The Event handling behavior field can be set to one of options:

• Wait for tool call results (default)
• Interrupt tool calls

Assuming the agent requested to execute tools A and B and tool B already being completed, the following describes how each option behaves when an event is received.

Wait for tool call results

The process waits for all tool calls to complete before handling the event. For the example above, the following sequence of messages would be sent to the LLM after both tools complete:

1. Tool A: Tool A result
2. Tool B: Tool B result
3. Event message: Content from event message

Interrupt tool calls

When an event is received while other tool calls are still in progress, the process will cancel the tool execution and directly return a list of messages to the LLM:

1. Tool A: Tool A execution was cancelled
2. Tool B: Tool B result
3. Event message: Content from event message

Response

Configure the response format by specifying how the model should return its output (text or JSON) and how the connector should process and handle the returned response.

The outcome of an LLM call is stored as an assistant message designed to contain multiple content blocks.

• This message always contains a single text content block for the currently supported providers/models.
• The connector returns the first content block when handling the response, either as a text string or as a parsed JSON object.

Field	Required	Description
Response format	Yes	Instructs the model which response format to return. This can be either text or JSON. JSON format support varies by provider and model.
Include assistant message	No	Returns the entire message returned by the LLM as responseMessage, including any additional content blocks and metadata. Select this option if you need more than just the first response text.

As the agent context is only needed outside the ad-hoc sub-process when modeling an external feedback loop or processing, there is an additional field to configure whether the context should be returned as part of the response:

Field	Required	Description
Include agent context	No	Returns the agent context variable as part of the response object. Necessary when modeling a user feedback loop in combination with an AI agent process as otherwise the context will only be kept in the process' internal state. Only applicable to the AI Agent Process implementation.

Text response format

If not configured otherwise, this format is used by default and returns a responseText string as part of the connector response.

Field	Required	Description
Parse text as JSON	No	If this option is selected, the connector will attempt to parse the response text as JSON and return the parsed object as responseJson in the connector response. Use this option for models that do not support setting JSON as response format (such as Anthropic models) in combination with a prompt instructing the model to return a JSON response. If parsing fails, the connector does not return an responseJson object, but only returns the original response text as responseText.

For an example prompt that instructs the model to return a JSON response, (see Anthropic documenation):

Output in JSON format with keys: "sentiment" (positive/negative/neutral), "key_issues" (list), and "action_items" (list of dicts with "team" and "task").

JSON response format

note

The JSON response format is currently only supported for OpenAI and Google Vertex AI models. Use the text response format in combination with the Parse text as JSON option for other providers.

If the model supports it, selecting JSON as response format instructs the model to always return a JSON response. If the model does not return a valid JSON response, the connector throws an error.

To ensure the model generates data according to a specific JSON structure, you can optionally provide a JSON Schema. Alternatively, you can instruct the model to return JSON following a specific structure as shown in the text example above.

Support for JSON responses varies by provider and model.

For OpenAI, selecting the JSON response format is equivalent to using the JSON mode. Providing a JSON Schema instructs the model to return structured outputs.

Field	Required	Description
Response JSON schema	No	Describes the desired response format as JSON Schema. See OpenAI's structured outputs documentation for examples.
Response JSON schema name	No	Depending on the provider, the schema must be configured with a name for the schema (such as Person). Ideally this name describes the purpose of the schema to make the model aware of the expected data.

For example, the following shows an example JSON Schema describing the expected response format for a user profile:

={
  "type": "object",
  "properties": {
    "userId": {
      "type": "number"
    },
    "firstname": {
      "type": "string"
    },
    "lastname": {
      "type": "string"
    }
  },
  "required": [
    "userId",
    "firstname",
    "lastname"
  ]
}

Assistant message

If the Include assistant message option is selected, the response from the AI Agent connector contains a responseMessage object that includes the assistant message, including all content blocks and metadata. For example:

{
  "responseMessage": {
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Based on the result from the GetDateAndTime function, the current date and time is:\n\nJune 2, 2025, 09:15:38 AM (Central European Summer Time)."
      }
    ],
    "metadata": {
      "framework": {
        "tokenUsage": {
          "inputTokenCount": 1563,
          "outputTokenCount": 95,
          "totalTokenCount": 1658
        },
        "finishReason": "STOP"
      }
    }
  }
}

To retrieve the response text from the responseMessage object, use the following FEEL expression (assuming the response variable is named agent):

agent.responseMessage.content[type = "text"][1].text

Output mapping

Specify the process variables that you want to map and export the AI Agent connector response into.

Field	Required	Description
Result variable	Yes	The result of the AI Agent connector is a context containing the following fields, depending on how the Response is configured. Set this to a unique value for every agent in your process to avoid interference between agents. context: The updated agent context if the Include agent context option is enabled. responseText: The last response text provided by the LLM if the Response Format is set to Text. responseJson: The last response text provided by the LLM, parsed as a JSON object if the Response Format is set to JSON or if the Parse text as JSON option is enabled. responseMessage: The assistant message provided by the LLM if the Include assistant message option is enabled.

Error handling

If an error occurs, the AI Agent connector throws an error and includes the error response in the error variable in Operate.

Field	Required	Description
Error expression	No	You can handle an AI Agent connector error using an Error Boundary Event and error expressions.

Retries

Specify connector execution retry behavior if execution fails.

Field	Required	Description
Retries	No	Specify the number of retries (times) the connector repeats execution if it fails.
Retry backoff	No	Specify a custom Retry backoff interval between retries instead of the default behavior of retrying immediately.

Execution listeners

Add and manage execution listeners to allow users to react to events in the workflow execution lifecycle by executing custom logic.