Building agents
Agents are goal‑driven and autonomous systems that can reason, run tasks, and interact with their environment through tools, knowledge sources, and external services. In IBM watsonx Orchestrate, agents are a foundational element of the agentic AI framework in which you can build dynamic and adaptive systems that can respond to changing context and conditions over time.
Building an agent is a core stage in the Agent Development Life Cycle (ADLC). This stage focuses on converting intent and design into concrete capabilities by configuring models, behavior, knowledge, and tools. It requires a clear understanding of what agents can do, how they must behave, and how their capabilities are implemented and combined to operate reliably within a broader agentic system.
If you’re new to AI agents or want a conceptual foundation first, see Introduction to AI agents.
Why build agents
You build agents when you need AI systems that do more than generate responses. Agents are designed to pursue goals, decide, and act over time within defined boundaries.
With agents, you can:
Run multi‑step and long‑running tasks.
Combine reasoning with knowledge retrieval and tool usage.
Encapsulate behavior and responsibility.
Adapt dynamically to changing context or system state.
Scale capabilities through specialization and collaboration across multiple agents.
Building agents is most appropriate when:
The system must choose between actions, request clarification, or adapt its strategy dynamically.
The solution requires state, context, or continuity over time.
Actions require guardrails, approvals, or escalation to humans.
The agent must coordinate knowledge sources, tools, APIs, or services.
Multiple agents are required to specialize, delegate, validate, or orchestrate work as part of a larger agentic system.
Process of building an agent
Build agents by defining what they know, how they behave, what they can do, and how users interact with them. The following points break down each design area with direct links to the relevant tasks.
Define your agent's onboarding experience
Clarify your agent’s purpose and capabilities so users and systems know what it can do. You can customize the welcome message and starter prompts to introduce the agent clearly and help users begin common tasks. Also, adjust the light‑gray helper text to give quick, practical guidance on how to interact with the agent, such as example inputs or limitations. Together, these elements create a clear and consistent user experience.
Learn more: Use the following topics to define agents' onboarding experience:
Define how agents decide what to do next
Select the AI model and agent style that shape your agent’s reasoning and thinking behavior. Select a model based on your agent’s goals and choose an agent style, such as ReAct or Plan-Act, that determines how the agent reasons, acts, and orchestrates tools. Together, these choices guide how the agent interprets inputs, produces responses, and runs tasks.
Learn more: Use the following topics to define the AI model and style for your agents:
Define how users interact with the agent
Specify how users engage with the agent, whether through text or text with rich elements, or with voice input enabled. Specify how the agent might deliver rich responses, such as formatted text, links, cards, or multimedia. For voice interactions, outline the approach for configuring voice settings, including available voices, languages, and any customization options.
Learn more: Use the following topics to configure ways of communication to your agents:
Define what the agent knows
Provide access to grounding information beyond the base AI model. It includes documents, databases, and other content repositories that inform the agent’s responses.
Learn more: Use the following topics to add knowledge to your agents:
Define what the agent can do
Enable your agents to act by starting tools, APIs, workflows, or services. It moves the agent from “answering questions” to “getting work done.”
Learn more: Use the following topics to add tools to your agents:
Define how multiple agents coordinate
Use multi‑agent orchestration to enable coordination across multiple specialized agents to solve problems that are too complex, broad, or context‑dependent for a single agent.
Learn more: Use the following topics to implement multi‑agent orchestration to your agents:
Define what the agent is allowed to do
Implement design decisions and constraints that govern the agent’s behavior. It includes instructions, guidelines, tones, and safety boundaries that shape how the agent responds and acts.
Learn more: Use the following topics to configure behavior to your agents:
Enable document-based interactions in chat
Allow users to upload documents directly into the chat so your agent can analyze, extract, and reference information from them. Enabling document‑based interactions expands your agent’s capabilities beyond conversational answers, supporting workflows like reviewing files, summarizing content, or finding details within user‑provided documents.
Learn more: Enable users to upload documents that agents can analyze, summarize, or extract from.
Known issues
For known issues related to building agents, see Known issues for building agents.