# AI Agent Example

This training agent is a “chat + tools” example. It searches books by calling the `/train_rest` saga. It can also render results as a rich HTML card UI.

It is configured in the **Data Science → GenAI Models** screen. It depends on the training assets from the other examples.

### Before you start

* The training runners are installed and running.
* The `/train_rest` saga exists and is `ACTIVE`. See [API Flow Examples](https://docs.rierino.com/examples/training-examples/api-flow-examples).
* A runner is allowed to serve GenAI models (`train_rpc`). See [Microservice Examples](https://docs.rierino.com/examples/training-examples/microservice-examples).
* You have an LLM provider key stored as a secret.

{% hint style="info" %}
For OpenAI, store `rierino.system.openai.apikey` key as a secret. In local setups this is typically `globalsecrets.properties`. In Kubernetes this is typically the `global-secrets` Secret.
{% endhint %}

### What you’ll build

* A GenAI agent with sample system instructions and a book-search goal.
* A **tool saga** entry that lets the agent call `/train_rest`.
* An optional **tool state** entry (the training `dummy` model) for safe additional data access.
* An optional **interface** so the agent can respond with UI cards.

### End-to-end flow (what happens at runtime)

1. The user asks for books (author/title/keywords).
2. The LLM decides to call the `/train_rest` tool saga.
3. `/train_rest` calls Open Library via an outbound REST step.
4. The agent formats results.
5. It returns an HTML-based result card.

### Configure the model (walkthrough)

{% stepper %}
{% step %}

### 1) Define the agent (purpose + allowed runner)

Fill the model definition. Keep the instructions concrete. Limit **Allowed For** to the runner you want serving the agent, unless it should be running within all microservices.

<figure><img src="https://1659095931-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcnDk3J1AzTgg2NFrGPlh%2Fuploads%2F85IkpeawZ5dNQLBHQtxW%2Fimage.png?alt=media&#x26;token=555a00da-3c72-4628-86bd-a7625b6f6d0d" alt=""><figcaption><p>Training Agent Example</p></figcaption></figure>
{% endstep %}

{% step %}

### 2) Select the LLM provider + API key secret

Pick **OpenAI** (or your provider). Reference the API key through a secret entry.

<figure><img src="https://1659095931-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcnDk3J1AzTgg2NFrGPlh%2Fuploads%2FPDnBlN8Q33xGVFYCGBHo%2Fimage.png?alt=media&#x26;token=7fd44e99-8dcf-415f-9ca0-79ede207e7aa" alt=""><figcaption><p>Training Agent LLM Model</p></figcaption></figure>
{% endstep %}

{% step %}

### 3) Add tools (make it actionable)

Add the `/train_rest` saga as a **Tool Saga**. This is what turns a chat-only agent into an agent that can act.

Add `dummy` as a **Tool State**. Keep it read-only unless you need writes.

<figure><img src="https://1659095931-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcnDk3J1AzTgg2NFrGPlh%2Fuploads%2FODLOhIlic4sx4dkfN4gr%2Fimage.png?alt=media&#x26;token=5c34ac4c-b187-42fd-905e-defa58372646" alt=""><figcaption><p>Training Agent Tools</p></figcaption></figure>

{% hint style="info" %}
Tool sagas work with an input schema. Schema nudges the LLM into correct parameter shapes.
{% endhint %}
{% endstep %}

{% step %}

### 4) Enable interfaces (optional, but recommended)

Enable interface responses. Add the book listing UI.

This example uses `HandlebarsDisplay`. That widget renders HTML from a template.

<figure><img src="https://1659095931-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcnDk3J1AzTgg2NFrGPlh%2Fuploads%2FfuquLAb0asn89sqTUtW7%2Fimage.png?alt=media&#x26;token=51fa8646-c59e-4a11-88fd-1511195da48d" alt=""><figcaption><p>Training Agent UIs</p></figcaption></figure>

{% embed url="<https://www.youtube.com/watch?v=jMARJDxzk24>" %}
{% endstep %}

{% step %}

### 5) Add the Handlebars template

Add a Handlebars template for the interface. The training template was generated by the 'Template Assistant' agent.

<figure><img src="https://1659095931-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcnDk3J1AzTgg2NFrGPlh%2Fuploads%2FamB7kn9J8fKzReLDfRwh%2Fimage.png?alt=media&#x26;token=931e9823-590b-4f25-ba4d-22653971ee99" alt=""><figcaption><p>Agent Dynamic UI Template</p></figcaption></figure>
{% endstep %}
{% endstepper %}

### Run it

After you **Save**, the agent appears in the agent list.

<figure><img src="https://1659095931-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcnDk3J1AzTgg2NFrGPlh%2Fuploads%2FBnGCAATnGdKpdLEEKxk3%2Fimage.png?alt=media&#x26;token=2059ea80-08cd-4dc6-9924-aac081265167" alt=""><figcaption><p>AI Agent Listing</p></figcaption></figure>

Open the agent and try a prompt like:

* `Find books by "Isaac Asimov".`&#x20;
* `Show me the books with "The Hobbit" in title.`

You should see tool-backed results. With interfaces enabled, you’ll get a rich HTML response.

<figure><img src="https://1659095931-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcnDk3J1AzTgg2NFrGPlh%2Fuploads%2FFyC4Qr4uTJaC9sYAjgbx%2Fimage.png?alt=media&#x26;token=789f2a00-4992-48ce-8e3f-7d9b6c51cf1c" alt=""><figcaption><p>AI Agent Interaction</p></figcaption></figure>

### Call it via API (optional)

Agents are also available as backend APIs. Use these endpoints from the runner channel that serves the agent:

* [AI Agent APIs](https://docs.rierino.com/data-science/genai-models/ai-agent-apis)

Use the **Call Path** from the agent’s Definition tab. That value is the stable identifier for calling the agent remotely.

### Troubleshooting

* **Model can’t be called**: the agent is not in **Allowed For** for your runner.
* **LLM auth error**: secret is missing or not resolved on the runner.
* **Agent never uses tools**: `/train_rest` is not listed in **Tool Sagas**.
* **Tool call fails**: verify `/train_rest` works directly first. Start from [API Flow Examples](https://docs.rierino.com/examples/training-examples/api-flow-examples).
* **UI response is plain text**: interfaces are disabled or no interface is assigned.
* **Broken HTML**: Handlebars template has invalid syntax. Simplify and retry.

### Next steps

* Deep dive into model tabs and governance in [GenAI Models](https://docs.rierino.com/data-science/genai-models).
* Extend the tool saga patterns in [API Flow Examples](https://docs.rierino.com/examples/training-examples/api-flow-examples).
* Build more admin screens like the training UI in [UI Example](https://docs.rierino.com/examples/training-examples/ui-example).


---

# Agent Instructions: 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:

```
GET https://docs.rierino.com/examples/training-examples/ai-agent-example.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.