AI Agents
AI agents are software components that use large language models (LLMs) to understand requests, make decisions, and perform actions autonomously. They can interact with users, invoke tools, access external systems, and maintain conversation context to complete tasks.
Components of an AI agent
An AI agent is composed of four core components that enable reasoning, action execution, and context management.
| Component | Description |
|---|---|
| Model | The Large Language Model (LLM) responsible for reasoning and response generation |
| System Prompt | Instructions that define the agent’s role, behavior, constraints, and interaction style |
| Tools | Functions, APIs, connectors, or services that the agent can invoke during execution |
| Memory | Context and conversation state maintained across interactions |
Without tools, the agent is limited to generating responses without interacting with external systems. Without memory, the agent cannot maintain context across multi-turn conversations.
In WSO2 Agent Builder, you design agents visually inside an agentic integration, give them tools and memory, connect them to a model provider, and connect them to triggers such as a chat channel, an HTTP endpoint, or an event source. Agents can also work together, either one after another in a fixed order or under an orchestrator that delegates to them. See Multi-Agent Concepts.
Ways to create an agent
Open the Add Agent dialog from the Add Agent button on your agentic integration's overview, or from the Add Agent action on the Agents node in the WSO2 Agent Builder side bar.
| You want | Use | You get |
|---|---|---|
| An agent for this agentic integration | Add Agent → Create Agent | A single agent instance |
| An agent that can wait days for a person or an event and resume after a restart | Add Agent → Create Durable Agent | An agent that runs as a durable workflow |
| An agent reused across agentic integrations or projects | Add Agent → Create Agent Definition | A reusable template that you can share |
| An agent someone has already built | Add Agent → Pre-built Agents | An instance of an existing definition |
The last two are covered in Create an Agent Definition. For a durable agent, see Build a Durable Agent.
Connect an agent to a trigger
An agent runs when a trigger calls it. On the agent canvas, click Add Trigger and pick how the agent is reached:
| Trigger group | What it does | Options |
|---|---|---|
| Chat Channels | Incoming messages are passed to the agent, and its reply is sent back. | Agent Chat, Google Chat, Telegram, WhatsApp Business |
| API Endpoints | Exposes the agent at a URL. A caller sends a request and gets the agent's answer back. | HTTP |
| Event Sources | Runs the agent when something happens in another system. | For example Kafka, RabbitMQ, AWS SQS, Salesforce, GitHub |
| File Sources | Runs the agent when a file becomes available in a location. | Azure Files, FTP / SFTP, Local Files, SMB |
Agent Chat gives the agent an HTTP chat endpoint (for example POST /support-agent/chat) that you can also chat with from inside WSO2 Agent Builder. An agent can have more than one trigger. Each trigger appears under Entry Points in the side bar.
What an agent looks like in the canvas
Select an agent under Agents in the side bar, or on the agentic integration's overview, to open its canvas. The canvas shows the agent with everything connected to it:
- Triggers on the left, with Add Trigger to add another
- The AI Agent node in the middle, showing its role and instructions
- The model provider on the right
- Add Tool below the model provider, and the tools the agent can call
From the canvas, you can configure the following components of the agent:
- System prompt and agent behavior: Click the AI Agent node to open the Edit Agent panel, where you can configure the agent's role, instructions, and advanced settings.
- Memory configuration: Use Add Memory on the AI Agent node to configure conversational or persistent memory for the agent. For more information, see Memory.
- Tools: Use Add Tool to add tools and MCP servers that the agent can call during execution. For more information, see Tools.
- Gated tools (HITL): Mark a tool as requiring approval so the agent pauses and asks a person before it runs. For more information, see Gate Tools for Approval.
- Model provider configuration: Click the model provider node (for example, Default WSO2 Model Provider) to choose the provider the agent uses, or create a new one. For more information, see Model Providers.
The Evaluations and Tracing: Off / On buttons at the top right of the canvas open the agent's evaluations and turn tracing on or off.
Try it and run
To chat with an agent that has an Agent Chat trigger:
- On the agent canvas, click the Agent Chat trigger. This opens the Chat Agent Service view, where the agent runs between Start and Return.
- Click Chat at the top right.
- If the agentic integration isn't running yet, WSO2 Agent Builder asks whether to run it. Select Run Integration.
The Agent Chat panel opens next to the canvas. Send a message to see the agent's reply.
The chat reuses the same session across messages, so you can test memory-aware conversations during development. Use Clear Chat to start a new conversation.
Common pitfalls
| Symptom | Likely cause | Fix |
|---|---|---|
| Agent doesn't pick the tool you expected. | Tool description is vague, or the system prompt doesn't mention when to use the tool. | Tighten the tool description; add a one-liner trigger condition in Instructions. |
| Agent's first response is empty or fails. | You aren't signed in, so the Default WSO2 Model Provider can't be used. | Sign in to WSO2 Agent Builder, then run Configure default WSO2 model provider from the Command Palette. |
| Agent drifts off-topic over a long conversation. | Memory is full and trimming is dropping the system prompt context. | Lower Max Messages Per Key (MSSQL) or use a larger-context model. |
| Same input produces wildly different responses. | Temperature is high on the model provider. | Lower temperature on the provider's Advanced Configurations. |
| Running the agentic integration fails with "default model provider not configured". | wso2aiKey missing from Config.toml. | Run Configure default WSO2 model provider from the Command Palette again. |
What's next
- Creating an Agent - Learn how to create and configure agents.
- Create an Agent Definition - Build a reusable agent template and share it across projects.
- Tools - Add functions, connectors, and MCP servers to your agents.
- Multi-Agent Concepts - Run agents in sequence, or under an orchestrator.
- Gate Tools for Approval - Pause a tool call for human-in-the-loop approval before it runs.
- Memory - Configure conversational and persistent memory.
- Observability - Monitor traces, logs, and execution details.
- Identity & Access Management - Secure agents and tools with identity and access control.
- Evaluations - Test and evaluate agent behavior and response quality.