> ## Documentation Index
> Fetch the complete documentation index at: https://help.treble.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> AI agent capable of holding a natural conversation and taking autonomous actions using tools.

The **AI Agent** lets you design conversational flows that handle processes with multiple possibilities. Its main strengths are the ability to integrate **tools** tailored to your business needs and the flexibility of defining its behavior directly in the instructions, without adding unnecessary complexity.

You don't need to write those instructions by hand: when you [create an agent](/en/docs/main-platform/ai-center/create-agent), Treble drafts them from what you describe. This page explains what they contain, how to adjust them and what the agent can do.

## Is it for you?

<Tabs>
  <Tab title="✅ Ideal if you need to">
    * You have a complex process that you want AI to manage.
    * There are multiple paths within the same conversation.
    * You need to define different exit or escalation rules.
    * You want to advance a sales process.
    * You want to reduce response time to prospects.
  </Tab>

  <Tab title="❌ Not ideal if">
    * You only need to send a fixed message or a template, with no conversation involved.
    * The flow is solved with question-and-answer blocks and simple conditionals.
  </Tab>
</Tabs>

## Use cases

* Advanced lead qualification with multiple exit routes.
* Automated post-sale information delivery.
* Communication with attendees after registering for a webinar.
* Assistance to help the user choose a product among several options.
* Automatic follow-up for abandoned carts.

<div class="hr" />

## How to read the generated instructions

The instructions Treble writes follow a consistent structure. Knowing it helps you quickly locate what to modify when the agent doesn't behave as you expect:

| Section                    | What it contains                                                    | When to touch it                                                     |
| -------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Identity and voice**     | Who the agent is, tone and style.                                   | The agent sounds too formal, cold or long-winded.                    |
| **Goal, scope and limits** | What it must achieve and what it can't talk about.                  | The agent answers topics outside your business.                      |
| **Steps and rules**        | The order of the conversation and its criteria.                     | It asks for data in the wrong order or doesn't close when it should. |
| **Tools**                  | When to call each tool and what to validate first.                  | A tool isn't used, or is used at the wrong time.                     |
| **Edge cases**             | What to do if information is missing or the contact goes off track. | A situation comes up that the agent didn't know how to handle.       |
| **Exits and escalation**   | When to finish, when to hand off and what to log.                   | Conversations don't reach the right team.                            |

<Tip>
  Adjust one section at a time and test in the playground after each change. Rewriting the whole prompt at once makes it very hard to know what improved or worsened the behavior.
</Tip>

### Writing the instructions yourself

If you'd rather start from a blank page, or want to understand what the generator is doing, this is the recommended structure:

1. **Context and objective**
   * Explain what the agent must accomplish and in which scenario it is used.
2. **Tone and style**
   * Indicate the desired register (for example, professional and clear).
3. **Available knowledge**
   * Indicate when to consult the knowledge base and when not to.
4. **Available tools**
   * Name, purpose, parameters, preconditions, and limits of each tool.
   * Usage rules: when to call it, what to validate beforehand, and what to return afterwards.
5. **Task description with explicit rules**
   * Steps to follow, priorities, completion and success criteria.
   * What to do if information is missing and how to request it.
6. **Capabilities and limitations**
   * What the agent can do and what it cannot do (and must not promise).
7. **Concrete examples**
   * Samples of correct inputs and outputs, plus one or two counterexamples.
8. **Reasoning**
   * Reminder to think step by step before responding.
9. **Escalation and exits**
   * When to finish, when to escalate, and which data to log.

Start with a limited scope, add tools incrementally, and expand coverage as the results become consistent.

💡Once your agent responds correctly in the playground, go to the **Conversation Builder** and add the **AI Agent** block to your flow. You'll find it in the advanced blocks section.

<img src="https://mintcdn.com/trebleai/YSdZhfVf8ZqT-MDw/images/TOMNodeES.jpg?fit=max&auto=format&n=YSdZhfVf8ZqT-MDw&q=85&s=a39b92aaf94056db04ab5e0ad16e2d76" alt="AI Agent block inside the conversation builder" width="658" height="148" data-path="images/TOMNodeES.jpg" />

<div class="hr" />

## Tools

The AI Agent can use different tools to perform actions inside or outside the conversation. These tools expand its capabilities, allowing it to consult information, create tickets, or update properties in external systems like HubSpot, in addition to interacting with Treble's native functions.

When you generate an agent, Treble picks the tools it needs and inserts them into the instructions. The ones that require data from you are flagged as pending configuration; you can complete them and add others from the [editor](/en/docs/main-platform/ai-center/configure-agent).

### General

* **Search the Web** — Searches the internet for updated or contextual information.
* **Send document** — Sends a file to the user during the conversation.
* **Send image** — Sends an image to the user during the conversation.

### Treble

* **Read variable** — References the value of a variable inside the instructions.
* **Save answer as variable** — Stores the contact's answer in a Treble variable.
* **Transfer to an agent** — Escalates the conversation to a human agent in Treble.
* **Send conversation** — Sends the contact to another Treble flow.
* **Close conversation** — Ends the interaction after the time you define.

### HubSpot

* **Transfer to an agent** — Sends the conversation to another agent or team within HubSpot.
* **Create ticket** — Generates a new ticket with the collected information.
* **Read Contact Property** — Consults the value of a specific property of a contact.
* **Save / Edit property** — Updates a contact property with data from the conversation.

### Advanced

* **API Call** — Makes a call to an external API with fixed values or with variables the agent has collected. See the [API tool guide](/en/docs/main-platform/ai-center/agents/ai-agent/api-tool).
* **Connected Apps** — Executes actions in the applications you connected to Treble, such as [Google Calendar](/en/docs/main-platform/ai-center/agents/ai-agent/google-calendar) or [Shopify](/en/docs/main-platform/ai-center/agents/ai-agent/shopify-usage).

<Note>
  HubSpot tools only appear if you have the integration connected, and **Connected Apps** shows only the applications you already linked to your account.
</Note>

<div class="hr" />

## Frequently asked questions

<AccordionGroup>
  <Accordion title="What is the AI Agent?">
    It is an AI agent designed to handle conversational flows with multiple possibilities, integrating tools and advanced logic to execute automated tasks.
  </Accordion>

  <Accordion title="Do I have to write the prompt myself?">
    No. You describe what you need, answer a few questions, and Treble drafts the instructions, picks the tools and builds the knowledge base. Your job is to review the result, complete the pending tools and test it.
  </Accordion>

  <Accordion title="Do I need to know how to code to configure it?">
    No. All the setup is done from the Treble interface.
  </Accordion>

  <Accordion title="Can the agent understand WhatsApp voice messages?">
    Yes. The agent can **understand voice messages sent by users through WhatsApp** and will automatically reply with text in the conversation.
  </Accordion>

  <Accordion title="What happens if the agent doesn't behave as expected?">
    Review the instructions and try to make them more explicit. Locate the matching section in the table above and add the case that failed as a concrete example.
  </Accordion>

  <Accordion title="Can I combine this agent with other flow nodes?">
    Yes. The agent can be integrated into a broader flow and can activate or close conversations, save responses, or call external tools according to your rules.
  </Accordion>

  <Accordion title="Which tools can the agent use?">
    **General**, **Treble**, **HubSpot** and **advanced** tools, including actions such as creating tickets, reading or editing properties, sending documents, transferring conversations, calling an API, or searching for information on the web.
  </Accordion>

  <Accordion title="How do I test my setup before launching it?">
    Use the [playground](/en/docs/main-platform/ai-center/playground) to run controlled tests with different inputs, and send yourself a test conversation on WhatsApp. Iterate until the agent responds correctly in every scenario.
  </Accordion>

  <Accordion title="Can the agent understand images?">
    Yes. The agent can understand images sent through WhatsApp and use what it sees to guide its actions. For example, it can recognize objects, read text in screenshots, or interpret elements in the image to decide what to do.

    However, the agent does not generate or create images. Its visual capability focuses on interpreting and acting on existing images, not producing new ones.
  </Accordion>

  <Accordion title="How do I handle complex or exceptional cases?">
    Define clear exit or escalation rules. If the agent cannot resolve a situation, transfer the conversation to a human agent or log the event in a ticket.
  </Accordion>

  <Accordion title="Can the agent learn or adapt over time?">
    It does not automatically learn from each interaction, but you can **improve its behavior** by iterating on the instructions and adjusting the tools or exit conditions.
  </Accordion>
</AccordionGroup>

## Important considerations

<Note>
  **Privacy:** Inform users that their data will be stored and comply with applicable regulations (GDPR, etc.).
</Note>