Building an agent
Create an agent that completes tasks and streamlines business processes. Choose a mode (Conversational, Structured, or Decision Engine), use a Boomi-managed model or your own, and add the tasks, tools, and guardrails that shape its behavior.
Prerequisites
To build, edit, and deploy agents and tools, you must have one of the following roles:
- Agent Garden Administrator
- Agent Garden Developer
- A custom role with privileges (Agent Garden Access, Agent Create, Agent Edit, Agent Feedback Submit, Agent Garden Feedback View)
Refer to Agent Garden for details on adding roles and setting up custom privileges.
Important considerations
- Conversational agents can respond with text, images, and chart visualizations in the Agent Garden's conversational experience. Image links also appear in agent responses in the Message step from processes using the Agent step. Videos are currently not supported.
- If your agent requires deep step-by-step analysis and reasoning, turn on Extended Thinking. Keep in mind that this setting increases latency. Refer to Choosing a model configuration to learn more.
- If Extended Thinking is on and the agent has no guardrails set, the chat streams the agent's plan in real time.
- With Extended Thinking on, conversational agents retain tool-response data across the session. This reduces repeated tool calls and helps the agent work with larger datasets, such as attached glossaries and knowledge bases, without losing access to earlier results as the conversation continues. Structured mode and Decision Engine mode are single-turn and don't carry session memory.
- Context window limit for Boomi-managed models: The user prompt, agent goal, tasks, and instructions combined cannot exceed 200K input tokens. Self-managed models inherit their context window limits set by the provider.
Step 1: Building the agent profile
- Navigate to Agent Garden > Agent Designer (plus icon).

- Select one of the following options:
- Select Blank Template to create an agent from scratch without a starter template. This option generates blank configuration fields and is recommended for experienced users.
- Select Build with AI to describe your agent’s goal and have AI fill in the profile, tasks, instructions, and guardrails. You can edit everything it generates. This option is recommended for new users. Include details about each task and any tools the agent calls, such as an API that returns data. The field supports up to 2,000 characters.
- Select Import Agent to import a YAML file that contains a configuration of an agent built in the Agent Designer from the Boomi Marketplace. YAML files are generated when you export an agent.
- Select Explore Templates Gallery to start from one of over 100 editable agent templates:
- Deploy: The agent is ready to use.
- Configure: The agent needs credentials for its tools, such as an API key.
- In Profile, enter the goal of the agent. If you are building with AI or a template, this goal is pre-populated. However, you can make edits and additions to the goal. The goal displays on the main agent page when the user enters a prompt. It also provides information to the LLM about its purpose. The Goal field supports up to 2,000 characters.
- Enter a name to identify the agent.
- Optional: Select Edit next to Agent Photo to select an avatar and color for the agent.
- Choose your agent’s mode based on its use case:
-
Conversational (default) - The AI agent responds in natural language text. This mode is ideal for conversational agents where the user may have follow-up questions after the initial prompt. The agent can use chat history and context to respond to the user and achieve its goal. Refer to Setting agent personality and tone for details on personality and tone settings.
- Configure the personality for the agent’s responses. These settings control the agent’s temperature, which includes how random and varied its responses are and how it reasons to achieve its tasks.
- Select the voice and tone for the agent’s responses.
- In Conversation Starter, select Add new starter to provide prompts users can enter to start chatting with your agent or select Give me some ideas to get AI-generated conversation starters. These starter prompts display as clickable buttons on the agent’s main conversation page so users can quickly get started.

-
Structured - The AI agent receives JSON input from Boomi Integration and responds in a consistent, structured JSON format. This mode is ideal for workflows that use the Agent step where the agent’s response is consumed by downstream systems. The response is single turn, meaning the agent has a single input and output with no reference to previous responses. Refer to Using Structured agent mode for details.
-
Decision Engine - The AI agent receives structured JSON input and returns a validated, structured decision that matches your schema. This mode is ideal for business logic such as triage, routing, and approval workflows. Unlike Structured mode, the agent can look up data, such as purchase order details or user entitlements, while it makes the decision. The response is single turn. Add the agent to workflows that use the Agent step where the agent’s response is consumed by downstream systems. Refer to Using Decision Engine mode for details.
-
- Select Save and Continue.
Step 2: Configuring the agent
-
In Configuration, select Change Model to attach a model to your agent. By default, two Boomi-managed models are available:
- Standard (Claude Sonnet 4.5): Suited for most everyday agent tasks including content generation, analysis, and coding. Provides responses with moderate to high latency. Best for well-defined tasks with predictable output structure where intermediate reasoning steps do not improve accuracy.
- Fast (Claude Haiku 4.5): Best for high-volume tasks like extraction, classification, sentiment analysis, and summarization. Provides responses with low latency.
Refer to Choosing a model configuration for guidelines and recommendations.
Select Self Managed to attach models from your own LLM provider accounts (OpenAI, Google, and Anthropic). Refer to Connecting models to Agentstudio and Adding a model to an agent to learn how to connect your accounts and attach models.
-
Optional: Select Extended Thinking when you want the agent to perform a deep, step-by-step analysis to generate a response. If the agent has no guardrails set, the chat streams the agent's plan in real time. Available for Boomi-managed models. Review What is Extended Thinking? for details.
-
Optional: In File Upload, turn on the Allow files to be uploaded toggle to let users send documents and images to the agent. The toggle is off by default. When enabled, select at least one format under Allowed Formats:
- Document Formats — PDF, DOCX, XLSX, CSV, TXT
- Image Formats — PNG, JPEG
Refer to Enabling file uploads for more information. Self-hosted agents do not support file upload.
-
Select Save and Continue.
Step 3: Adding tasks
Refer to Writing tasks and instructions for best practices and conceptual information.
- In Tasks, select Add New Task to create an objective for the agent to accomplish. Each task includes instructions, similar to subtasks, with details about accomplishing the task. Optionally, you can attach a tool to a task to provide the LLM with capabilities it needs to perform the task. Tasks and instructions do not need to be in sequential order.
- Enter a task name.
- Enter a detailed description of the task and what the agent must do to perform the task. Be as detailed as possible to help the LLM understand its objective.
- Enter instructions to break the task into multiple steps. This helps the LLM understand each part of the task and how to accomplish it. Instructions do not need to be in order. The agent uses reasoning to determine the correct order based on the task and goal.
- Optional: Select Give me some ideas to let AI generate ideas for instructions based on your detailed task description.
- Select Add task.
- Repeat step a through c for each task.
- Optional: Select Tools in a task to add a capability or function so the agent can accomplish the task. For example, if the task involves the agent retrieving information from an API, you can attach an API tool you created. You can also select Create New Tool to create and attach a new tool. Refer to Identifying and adding capabilities to agent to learn about the tool types you can create.
- Select Attach Tool.
- Select the checkbox in the list view for any tools you want to add to the task.
- Select Attach.
- Optional: Select Requires Approval to require the agent to ask the user if it can proceed with an action performed through the tool. This is useful when the agent performs a permanent update, changes a field in a record, or creates something new in a system.
- Optional: Select Data Passthrough to control how the agent returns tool output:
- Selected: The raw output, such as an API response, goes directly to the chat. For an integration tool, this is the integration’s execution status.
- Deselected: The agent processes the data and responds in natural language. Refer to Data passthrough setting for examples.
- Select Save.
- Optional: Select Glossaries in a task to attach a Meta Hub business glossary. Glossaries give the agent access to your organization's terminology so it can accurately interpret prompts using organization-specific definitions. Refer to Connecting a business glossary to your agent for details. Glossaries are not available for self-hosted agents.
- Select Attach Glossary.
- Select Attach next to the glossary you want to attach.
- Close the panel.
- Optional: Select Knowledge Bases in a task to attach a Knowledge Hub knowledge base. Knowledge bases give the agent access to your organization's data through retrieval-augmented generation (RAG), so it can ground its responses in real enterprise content. Refer to Connecting a knowledge base to your agent for details. Knowledge bases are not available for self-hosted agents.
- Select Attach Knowledge Base.
- Select a repository to narrow the list of available knowledge bases.
- Select one or more knowledge bases from the list.
- Optional: Select Configuration to change the retrieval mode and result limit for each knowledge base you attach. Select Save.
- Optional: Add metadata filters using the drop-downs populated from the knowledge base's schema.
- Select Save.
- Close the panel.
- Select Save and Continue.
Step 4: Creating guardrails

- In Guardrails, enter a blocked message. This message displays any time a user prompts the agent for a response that violates the agent’s restrictions and ethical guidelines. Refer to Creating guardrails for more information.
- Select Add Denied Topics to enter a topic the agent cannot respond to, along with a few sample phrases. For example, a bank may want its AI agent to avoid any conversation related to investment advice or engage in conversations related to cryptocurrencies. In this case, you can enter “investment advice” and “cryptocurrency” as denied topics. You can set a maximum of 30 denied topics. The maximum number of sample phrases per topic is 5. Topic descriptions can be up to 200 characters.
- Select the Word Filters tab. Enter words or short phrases that trigger the agent to respond with the blocked message. For example, you can add words such as steal, hack, and fraud.
- Select the Custom Regex Pattern tab. Enter patterns of sensitive data, such as email addresses and phone numbers, that will trigger a blocked message from the agent. For example, you can add
^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$for email addresses.
- Select Save and Continue.
Step 5: Testing an agent
Refer to Testing and troubleshooting an agent for more information and best practices.
Important considerations
- Testing your agent may count against any usage limits.
- Your agent remains in a draft state until you package and deploy it. You can edit agents at any time without affecting active deployments. Changes only go live when you create and deploy a new package.
- Self-hosted agents must be tested in an Integration process.
Test your agent before and after you add tasks and guardrails. Testing iteratively helps you easily identify which configuration is causing an issue and which configurations are working correctly.
To test agents deployed to self-hosted runtimes, refer to Agent step testing and troubleshooting.
To test an agent deployed to a Boomi-managed runtime cloud:
- In the Test Agent window, select a runtime cloud to choose which regional cloud runs your test session. Enter a prompt or select a conversation starter to test the agent's responses and capabilities. When the agent responds, select Show Trace to inspect the internal decision-making process. The trace provides a detailed breakdown of how the agent interprets inputs, applies logic, and generates responses, and indicates errors with tool calls. This is useful for troubleshooting and making edits to your agent.

Step 6: Packaging and deploying an agent
Packaging creates a versioned snapshot of your agent. Deploying sends the package to an environment, where the agent runs. You can deploy to either of these runtimes, and your own models work with both:
- Boomi-managed runtime cloud: Boomi hosts regional infrastructure that runs your agent.
- Self-hosted Flex runtime (Early Access): Your agent runs in your own infrastructure. Refer to Deploying an agent to a Flex runtime.
Before you deploy, make sure the runtime you want is attached to an environment on the Environments page in Agentstudio:
- Boomi-managed runtime cloud: Attach the runtime cloud to an environment yourself. The default Agent Garden Production and Agent Garden Testing environments already have a runtime cloud attached. Refer to Attaching and detaching an agent runtime cloud and Agent runtime clouds and environments.
- Self-hosted Flex runtime: Flex runtimes and their environments appear automatically.
Keep in mind:
- Self-hosted agents can deploy only to self-hosted runtimes attached to production environments.
- If your agent uses your own model, you can deploy it only to the environments you selected on the model connection. Refer to Connecting models to Agentstudio.
- Navigate to Agentstudio > Agent Garden > Agents and open your agent.
- In the Review tab, select Create > Package & Deploy.
- Select the Environment with the runtime you want, then select Create Package & Deploy. Agentstudio assigns the package version number.
After you deploy:
- Conversational agents on a Boomi-managed runtime cloud: Users can chat with the agent in Agent Garden. Refer to Using AI agents and Tracing sessions of Boomi Agent Garden agents.
- Self-hosted, Structured mode, and Decision Engine mode agents: These agents cannot be used with Agent Garden chat or EmbedKit. Self-hosted agents cannot be conversational at this time. Use them in an integration process with the Agent step. For self-hosted agents, select Go to Integration after you deploy. Refer to Configuring the Agent step.
Editing an agent does not affect active deployments. To release changes, deploy a new package version. For managing packages and deploying to multiple environments, refer to Deploying agents.
Next steps
- Add your agent to an integration process. Refer to Agent step to learn how to build agentic workflows.
- Embed conversational agents you create in Agentstudio directly into your own applications using EmbedKit. Get started with the GitHub repository and explore the Boomi Embedded documentation.
- Read Agent examples to get tutorials on building specific agents for real-world use cases. You'll learn how to use Agent step, how to create an API your agent can use to retrieve data, and more.
- Read Using AI agents. After you deploy your agent, users are able to see and interact with your agent in a conversational interface in the Chat screen.