Guide to Adding a Tool for an AI Agent

AI Agents and BPMN open up an exciting world of agentic orchestration, empowering AI to act with greater autonomy while also preserving auditability and control. With Camunda, a key way that works is by using an ad-hoc sub-process to clearly tell the AI agent which tools it has access to while it attempts to solve a problem. This guide will help you understand exactly how to equip your AI agents with a new tool.

How to build an AI Agent in BPMN with Camunda

There are two aspects to building an AI Agent in BPMN with Camunda.

1. Defining the AI Task Agent
2. Defining the available tools for the agent.

The AI Task Agent is the brain, able to understand the context and the goal and then to use the tools at its disposal to complete the goal. But where are these tools?

Adding new tools to your AI agent

The tools for your AI agent are defined inside an ad-hoc sub-process which the agent is told about. So assuming you’ve set up your Task Agent already—and you can! Because you just need the process model from this github repo. The BPMN model without any tools should look like this:

Basically I’ve removed all the elements from within the ad-hoc sub-process. The agent still has a goal—but now has no way of accomplishing that goal.

In this guide we’re going to add a task to the empty sub-process. By doing this, we’ll give the AI Task Agent access to it as a tool it can use if it needs to.

The sub-process has a multi-instance marker, so for each tool to be used there’s a local variable called toolCall that we can use to get and set variables.

I want to let the AI agent ask a human a technical question, so first I’m going to add a User Task to the sub-process.

Defining the tool for the agent

The next thing we need to do is somehow tell the agent what this tool is for. This is done by entering a natural language description of the tool in the Element Documentation field of the task.

Defining variables

Most tools are going to request specific variables in order to operate. Input variables are defined so that the agent is aware of what’s required to run the tool in question. It also helps pass the given context of the current process to the tool. Output variables define how we map the response from the tool back into the process instance, which means that the Task Agent will be aware of the result of the tool’s execution.

In this case, to properly use this tool, the agent will need to come up with a question.

For a User Task like this we will need to create an input variable like the one you see below.

In this case we created a local variable, techQuestion, directly in the task. We’ll then both assign this variable and define it for the task agent we need to call the fromAi function. To do that we must provide:

1. The location of the variable in question.
   • In this case that would be within the toolCall variable.
2. A natural language description of what the variable is used for.
   • Here we describe it as the question that needs to be asked.
3. The variable type.
   • This is a string, but it could be any other primitive variable type.

When all put together, it looks like this:

fromAi(toolCall.techQuestion, "This is a specific question that you’d like to ask", "string")

Next we need an output variable so that the AI agent can be given the context it needs to understand if running this tool produced the output it expected. In this case, we want it to read the answer from the human expert it’s going to consult.

This time, create an output variable. You’ll have two fields to fill in.

1. Process variable name
   • It’s important that this variable name matches the output expected by the sub-process. The expected name can be found in the output element of the sub-process, and as you can see above, we’ve named our output variable toolCallResult accordingly.

     

2. Variable assignment value
   • This needs to simply take the expected variable from the tool task and add it to a new variable that can be put into the toolCallResult object

So in the end the output variable assignment value should be something like this:

{ “humanAnswer” : humanAnswer}

And that’s it! Now the AI Task Agent knows about this tool, knows what it does and knows what variables are needed in order to get it running. You can repeat this process to give your AI agents access to exactly as many or as few tools as they need to get a job done. The agents will then have the context and access required to autonomously select from the tools you have provided, and you’ll be able to see exactly what choices the agent made in Operate when the task is complete.

All of this is available for you to try out in Camunda today. Learn more about how Camunda approaches agentic orchestration and get started now with a free trial here. For more on getting started with agentic AI, feel free to dig deeper into our approach to AI task agents.