> For the complete documentation index, see [llms.txt](https://docs.infotopics.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.infotopics.com/trulyp/ai/ai-agents/using-an-ai-agent.md).

# Using an AI agent

## Using an AI Agent

Once an AI agent has been created, tested, saved, and set to **Active**, it can be used by other parts of Trulyp or by an external application.

Agents are identified by their **slug**. The slug is the unique name of the agent.

For example:

```
customer-support-agent
```

{% hint style="warning" %}
Only **Active** agents can be used. **Draft** and **Paused** agents are not available to end users.
{% endhint %}

***

## Testing your agent

Before making an agent available to end users, test it to make sure it behaves as expected.

Open the agent and click **Test**.

Enter a JSON input payload and choose how you want to test the agent:

| Test type      | Description                                                                                               |
| -------------- | --------------------------------------------------------------------------------------------------------- |
| **Quick test** | Runs a single AI action. Use this when you only want to test a prompt.                                    |
| **Flow run**   | Runs the complete visual flow, including conditions, knowledge, structure builders, and connected blocks. |

### Example

If your AI action contains the following prompt:

```
Answer this customer question:

{{ question }}
```

Use this test input:

```json
{
  "question": "How do I reset my password?"
}
```

Click **Run flow** to execute the agent.

The test result shows the final output and the steps that were executed during the flow.

{% hint style="info" %}
Use **Quick test** while developing individual prompts. Use **Flow run** when you want to verify the complete agent before making it available to users.
{% endhint %}

***

## Using an agent in Trulyp

An AI agent can be called by another AI feature, a workflow, or a custom integration.

The calling feature sends input to the agent. The agent runs its visual flow and returns the final result.

### Chat-style input

For a chat-style agent, send the user's message as `message`:

```json
{
  "input": {
    "message": "How do I reset my password?"
  }
}
```

### Structured input

If an agent expects specific fields, send those fields inside `input`.

For example:

```json
{
  "input": {
    "customer_name": "Jane Doe",
    "order_number": "ORD-12345",
    "question": "Where is my order?"
  }
}
```

{% hint style="warning" %}
The field names must match the variables used in the agent's prompts. If a prompt uses `{{ question }}`, the input must include a `question` field.
{% endhint %}

***

## Calling an agent through the API

You can discover and run Active agents through the API.

### List available agents

To retrieve all available agents, call:

```http
GET /agents
```

This returns all **Active** agents, including information such as:

* Name
* Slug
* Description
* Expected input format
* Output format
* Usage notes

***

### Run the complete flow

To execute the complete visual flow of an agent, call:

```http
POST /agents/{agent-slug}/run
```

For example:

```http
POST /agents/customer-support-agent/run
```

Send the agent's data inside `input`:

```json
{
  "input": {
    "question": "How do I reset my password?"
  }
}
```

The API executes the complete visual flow and returns its final output.

#### Sending a message directly

For chat-style agents, you can also send `message` directly:

```json
{
  "message": "How do I reset my password?"
}
```

Trulyp automatically makes this message available inside the agent's input as `message`.

{% hint style="info" %}
Use `/run` when you want to execute the agent's complete visual flow.
{% endhint %}

***

## Calling a single AI action

If you only want to execute one AI action instead of the complete visual flow, use:

```http
POST /agents/{agent-slug}/invoke
```

For example:

```http
POST /agents/customer-support-agent/invoke
```

This is useful for simple agents that contain a single AI action.

A request can contain input and variables such as:

```json
{
  "input": {
    "question": "How do I reset my password?"
  }
}
```

By default, the agent uses the first AI action in its flow, unless a specific **AI Configuration** is provided.

{% hint style="warning" %}
`/invoke` does not execute the complete visual flow. Conditions, knowledge connections, workflows, and other connected blocks are not run.
{% endhint %}

#### `/run` vs `/invoke`

| Endpoint                           | Use when                                      |
| ---------------------------------- | --------------------------------------------- |
| `POST /agents/{agent-slug}/run`    | You want to execute the complete visual flow. |
| `POST /agents/{agent-slug}/invoke` | You only want to execute a single AI action.  |

***

## Chat agents

An agent can be configured as either a **One-shot** agent or a **Multi-turn chat** agent.

### One-shot agents

A **One-shot** agent treats every request as a separate interaction.

Use this for tasks such as:

* Summarising text
* Classifying data
* Extracting information
* Creating structured output
* Transforming content

Each request is processed independently.

### Multi-turn chat agents

A **Multi-turn chat** agent can maintain conversation history for a user.

Use this for:

* Support assistants
* Internal knowledge assistants
* Conversational interfaces
* Other ongoing conversations

#### Continuing a conversation

Send a `thread_id` to continue an existing conversation:

```json
{
  "input": {
    "message": "Can you explain that in more detail?"
  },
  "thread_id": 123
}
```

The agent uses the existing conversation history associated with that thread.

If no `thread_id` is provided, Trulyp creates a new conversation thread.

{% hint style="info" %}
Use the same `thread_id` for subsequent messages when you want the agent to retain the context of an existing conversation.
{% endhint %}

***

## Using an agent from another agent

You can call another saved agent from within a visual flow using the **Agent** block.

This allows larger processes to be split into smaller, reusable agents.

For example:

`Main support agent → Order lookup agent → Response agent`

In this flow:

1. The **Main support agent** receives the request.
2. The **Order lookup agent** retrieves or processes the relevant order information.
3. The **Response agent** uses that information to prepare the final answer.

The called agent returns its result to the parent flow. Blocks later in the parent flow can then use that result.

{% hint style="success" %}
Splitting complex processes into smaller agents can make flows easier to understand and allows specialized agents to be reused in multiple workflows.
{% endhint %}

***

## Choosing how to call an agent

The best way to use an agent depends on what you want to execute.

| Goal                                  | Recommended approach                 |
| ------------------------------------- | ------------------------------------ |
| Test an individual prompt             | **Quick test**                       |
| Test the complete agent               | **Flow run**                         |
| Run the complete flow through the API | `POST /agents/{agent-slug}/run`      |
| Run a single AI action                | `POST /agents/{agent-slug}/invoke`   |
| Maintain an ongoing conversation      | **Multi-turn chat** with `thread_id` |
| Run an agent from another agent       | **Agent block**                      |
| Discover available Active agents      | `GET /agents`                        |

{% hint style="success" %}
For most production integrations, use `/run` so the complete visual flow is executed as configured in the AI Agent Builder.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.infotopics.com/trulyp/ai/ai-agents/using-an-ai-agent.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.