Build your first AI agent

Beginner Time estimate: 45 minutes

Get started with Camunda agentic orchestration by building and running your first AI agent.

About

AI agents represent the practical implementation of agentic process orchestration within Camunda, combining the flexibility of AI with the reliability of traditional process automation.

In Camunda, an AI agent refers to an automation solution that uses ad-hoc sub-processes to perform tasks with non-deterministic behavior.

In this guide, you will:

• Run your AI agent using Camunda 8 SaaS or locally with Camunda 8 Self-Managed.
• Use an AI Agent connector to provide interaction and reasoning capabilities to the AI agent.
• Use an ad-hoc sub-process to define the tools the AI agent should use.
• Integrate a Large Language Model (LLM) into your AI agent.

After completing it, you will have an example AI agent running in Camunda 8.

Prerequisites

To build your first AI agent, see the prerequisites below depending on:

• Your working environment.
• Your chosen model.

Camunda 8 environment

To run your agent, you must have Camunda 8 (version 8.8 or newer) running, using either:

• Camunda 8 SaaS. For example, sign up for a free SaaS trial account.
• Camunda 8 Self-Managed. For example, follow Run your first local project.

Supported models

The AI Agent connector makes it easy to integrate LLMs into your process workflows, with out-of-the-box support for popular model providers such as Anthropic and Amazon Bedrock. It can also connect to any additional LLM that exposes an OpenAI-compatible API. See supported model providers for more details.

In this guide, you can try two use cases:

Setup	Model provider	Model used	Prerequisites
Cloud	AWS Bedrock	Claude Sonnet 4	An AWS account with permissions for the Bedrock Converse API. Anthropic Claude foundation models using the AWS console. See AWS documentation for details.
Local	Ollama	GPT-OSS:20b	Camunda 8 Run running locally. Ollama and GPT-OSS:20b installed. See Set up Ollama for details.

important

Running LLMs locally requires substantial disk space and memory. GPT-OSS:20b requires more than 20GB of RAM to function and 14GB of free disk space to download.

Step 1: Install the model blueprint

To start building your first AI agent, you can use a Camunda model blueprint from Camunda marketplace.

In this guide, you will use the AI Agent Chat Quick Start model blueprint. Depending on your working environment, follow the corresponding steps below.

SaaS

1. In the blueprint page, click For SAAS and select or create a project to save the blueprint.
2. The blueprint BPMN diagram opens in Web Modeler.

Self-Managed

1. In the blueprint page, click For SM and download the blueprint files from the repository.

note

If you’re using Camunda 8 Run and installed it using the starter package, the blueprint was already downloaded as part of it.

2. Open the blueprint BPMN diagram in Desktop Modeler.

About the example AI agent process

The example AI agent process is a chatbot that you can interact with via a user task form.

This process showcases how an AI agent can:

• Make autonomous decisions about which tasks to execute based on your input.
• Adapt its behavior dynamically using the context provided.
• Handle complex scenarios by selecting and combining different tools.
• Integrate seamlessly with other process components.

The example includes a form linked to the start event, allowing you to submit requests ranging from simple questions to more complex tasks, such as document uploads.

Step 2: Configure the AI Agent connector

Depending on your model choice, configure the AI Agent connector accordingly.

AWS Bedrock

Configure the connector's authentication and template for AWS Bedrock.

Configure authentication

The example blueprint downloaded in step one is preconfigured to use AWS Bedrock. For authentication, it uses the following connector secrets:

• AWS_BEDROCK_ACCESS_KEY: The AWS Access Key ID for your AWS account able to call the Bedrock Converse API.
• AWS_BEDROCK_SECRET_KEY: The AWS Secret Access Key for your AWS account.

You will configure these secrets differently depending on your working environment.

SaaS

Configure the secrets using the Console.

Self-Managed

Export the secrets as environment variables before starting the distribution. See Connector secrets for details.

See Amazon Bedrock model provider for more information about other available authentication methods.

Configure properties

In the blueprint BPMN diagram, the AI Agent connector template is applied to the AI Agent service task. See AI Agent connector for more details.

You can keep the default configuration or adjust it to test other setups. To do so, use the properties panel:

Ollama

Configure your local LLM with Ollama.

Set up Ollama

1. Download and install: Follow Ollama's documentation for details.
2. Confirm installation: Check the installed version in a terminal or command prompt by running ollama --version.
3. Start the local server: Start it using the application, or run ollama serve in a terminal or command prompt.
4. Pull the GPT-OSS:20b model: If it isn't installed by default, run ollama pull gpt-oss:20b in a terminal or command prompt to download the model.
5. Test: Ollama serves an API at http://localhost:11434 by default. To test it, open that URL in a browser or run this command in your terminal:

curl -X POST http://localhost:11434/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{"model":"gpt-oss:20b","messages":[{"role":"user","content":"Hello!"}]}'

Configure properties

The example blueprint downloaded in step one is preconfigured to use AWS Bedrock. Update the connector's configuration using the Model provider and Model sections to use Ollama instead.

Model provider

1. Select OpenAI Compatible from the Provider dropdown.
2. Enter http://localhost:11434/v1 in the API endpoint field. This is Ollama's default API URL.
3. No authentication or additional headers are required for the local Ollama API, so leave the remaining fields blank.

Model

1. Enter gpt-oss:20b in the Model field. This field is case-sensitive, so be sure to enter it in all lowercase.

tip

When configuring connectors, use FEEL expressions, by clicking the fx icon, to reference process variables and create dynamic prompts based on runtime data.

Step 3: Test your AI agent

Deploy and run your AI agent in your Camunda cluster.

important

Whether you are testing your agent in Camunda 8 SaaS or locally with Camunda 8 Self-Managed, make sure you’re running a cluster with version 8.8 or higher.

Depending on your working environment, test your agent by following the corresponding steps below.

SaaS

1. Open Web Modeler.
2. Select the Play tab.
3. Select the cluster you want to deploy and play the process on.
4. Open the Start form and add a prompt for the AI agent. For example, enter "Tell me a joke" in the How can I help you today? field, and click Start instance.
5. The AI agent analyzes your prompt, decides what tools to use, and responds with an answer. Open the Task form to view the result.
6. You can monitor the process execution in Operate.
7. You can follow up with more prompts to continue testing the AI agent. Select the Are you satisfied with the result? checkbox when you want to finish your testing and complete the process.

tip

Instead of using Play, you can also test the process within the Implement tab using Deploy & Run, and use Tasklist to complete the form.

Self-Managed

1. Deploy the process model to your local Camunda 8 environment using Desktop Modeler.
2. Open Tasklist in your browser at http://localhost:8080/tasklist.
3. On the Processes tab, find the AI Agent Chat With Tools process and click Start process.
4. In the start form, add a prompt for the AI agent. For example, enter "Tell me a joke" in the How can I help you today? field, and click Start process.
5. The AI agent analyzes your prompt, decides what tools to use, and responds with an answer.
6. Select the Tasks tab in Tasklist. When the AI agent finishes processing, you should see either a User Feedback or a Ask human to send email task waiting for you to complete.
7. You can monitor the process execution in Operate. Open it in your browser at http://localhost:8080/operate.
8. You can follow up with more prompts to continue testing the AI agent. Select the Are you satisfied with the result? checkbox when you want to finish the process.

What to expect during execution

When you run the AI agent process:

1. The AI agent receives your prompt and analyzes it.
2. It determines which tools from the ad-hoc subprocess should be activated.
3. Tasks can execute in parallel or sequentially, depending on the agent's decisions.
4. Process variables are updated as each tool completes its execution.
5. The agent may iterate through multiple tool calls to handle complex requests.

You can observe this dynamic behavior in real-time through Operate, where you'll see which tasks were activated and in what order.

Next steps

Now that you’ve built your first Camunda AI agent, why not try customizing it further?

For example:

• Add and configure more tools in the ad-hoc sub-process that the AI agent can use.
• Change the provided system prompt to adjust the behavior of the AI agent.
• Experiment with different model providers and configurations in the AI Agent connector.

You can also:

• Learn more about Camunda agentic orchestration and the AI Agent connector.
• Read the Building Your First AI Agent in Camunda blog.
• Explore other AI blueprints from Camunda marketplace.

Camunda Academy

Register for the free Camunda 8 - Agentic Orchestration course to learn how to model, deploy, and manage AI agents in your end-to-end processes.