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

# Agents

Everything in your workspace centers around agents. Powered by agentic workflows, these agents combine LLM reasoning with tools and data to complete tasks. They go beyond basic chatbots to deliver sophisticated, logic-driven automation.

### What Is an Agent

An Agent is the intelligent core of your workspace, designed to automate complex tasks and interact with users using your specific data and logic. An agent is your versatile AI worker: manage in Workspace, build and deploy in Designer, and monitor the performance in Observatory.

Every agent is built on three essential pillars:

<details open>

<summary><strong>Workflows</strong></summary>

Defined sequences of nodes that dictate the agent's behavior, decision-making, and logical progression.

</details>

<details open>

<summary><strong>Knowledge</strong></summary>

Custom data sources and documents that provide the agent with the specific context needed to give accurate, grounded answers.

</details>

<details open>

<summary><strong>Plugins</strong> </summary>

External capabilities and integrations that empower the agent to execute complex tasks.

</details>

A single Workspace can house multiple agents, allowing you to manage an entire suite of AI tools in one centralized hub. While each agent is tied to its specific Workspace, you are not limited to a single version; you can create multiple deployments for any agent to test different configurations or prompt variations simultaneously.

### Creating an Agent

Every agent starts from a Blueprint: a ready-made starting point that bundles workflows and the plugins a common use case needs.

{% stepper %}
{% step %}

#### Pick a Blueprint

In **Workspace > Agents**, select **Create New Agent**. Browse the Blueprint cards and select the one closest to what you want to build.

{% hint style="info" %}
Every agent you create is a Modern Agent, built on the current agent architecture.
{% endhint %}
{% endstep %}

{% step %}

#### Connect Its Plugins

Each plugin in the Blueprint needs an LLM Workspace integration to run. Pick one from the dropdown or select **+ Add new Integration** to create one inline. You can change these later.
{% endstep %}

{% step %}

#### Add the Agent Details

Name the agent and set its language, then select **Create**. Your agent appears in **Workspace > Agents.**

<details>

<summary><strong>Name</strong></summary>

Use a descriptive, unique name so you can tell agents apart in the table. A structured naming approach also enables a simplified [version control](/build/version-control.md) workflow.

</details>

<details>

<summary><strong>Primary language</strong></summary>

The agent's default language. The agent uses it to reply to new users and as the fallback when no other language applies. Your content is authored in this language; other languages are added as translations. Add more languages anytime under **Designer > Settings > Configuration**.

</details>

<details>

<summary><strong>Description (optional)</strong></summary>

Context for other makers in the Workspace to understand the agent's role.

</details>

<details>

<summary><strong>Avatar (optional)</strong></summary>

Upload an image, browse your Workspace's Media Manager, or connect an external URL.

</details>
{% endstep %}

{% step %}

#### Start Building

Your agent is ready. Head over to Designer to build, configure, and deploy it. Track how it performs in Observatory.
{% endstep %}
{% endstepper %}

### Accessing an Agent

To view the Agents table, go to **Workspace > Agents**. From here, you can:

* View all existing agents in your Workspace
* Create new agents
* Perform actions like edit, clone and replace existing agents

To access a specific agent, your options depend on your current vie&#x77;**:**

{% tabs %}
{% tab title="Workspace" %}
Select **Agents** from the sidebar and click on your agent.

<div data-with-frame="true"><figure><img src="/files/O6aZlfJiM50J63E0Wmq6" alt="" width="563"><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="Designer" %}
Click the agent selection card on the top to search for and switch between agents.

<div data-with-frame="true"><figure><img src="/files/a8Oqpgni3VgbFKDbXXVC" alt="" width="563"><figcaption></figcaption></figure></div>
{% endtab %}
{% endtabs %}

### Previewing an Agent

The **Live Demo** button lets you chat with your agent without deploying it. Use it to validate [workflow](/build/workflows.md) edits, prompt changes, or new Knowledge Base content before pushing them to a live channel. The chat itself behaves like a Webchat deployment, with additional controls for testing.

The button is docked to the right edge of Designer and is available from any tab. A status indicator below the play icon shows whether the agent's training is current. Click it to update the agent knowledge.

{% columns %}
{% column %}

#### <i class="fa-circle-check">:circle-check:</i> Trained&#x20;

<div data-with-frame="true"><figure><img src="/files/HFjojDIbMD9K06qvsJfd" alt="" width="47"><figcaption></figcaption></figure></div>

A check below the play button means the agent reflects your latest changes. The preview runs against the current Knowledge Base.
{% endcolumn %}

{% column %}

#### &#x20;<i class="fa-arrows-rotate">:arrows-rotate:</i>  Needs Retraining

<div data-with-frame="true"><figure><img src="/files/fOSqLYoATSwdMMRbsPqa" alt="" width="49"><figcaption></figcaption></figure></div>

A yellow indicator means the Knowledge Base have been made since the agent was last trained. Retrain before previewing if you want the demo to reflect your most recent edits.
{% endcolumn %}
{% endcolumns %}

The preview goes beyond a chat surface. You can target a specific workflow for the run, tune context like language or metadata, and view the finished session in Observatory:

<table data-column-title-hidden data-view="cards"><thead><tr><th>Title</th><th>Description</th></tr></thead><tbody><tr><td><h4><i class="fa-eye">:eye:</i></h4><h4>View in Observatory</h4></td><td>Opens <strong>Observatory > Sessions > Chat Sessions</strong> pre-filtered to this agent so you can inspect the last session</td></tr><tr><td><h4><i class="fa-arrows-rotate">:arrows-rotate:</i></h4><h4>Reload</h4></td><td>Restarts the conversation from the selected workflow </td></tr><tr><td><h4><i class="fa-gear">:gear:</i></h4><h4>Settings</h4></td><td>Opens the Preview Settings panel to tune how the run behaves and what context it carries</td></tr><tr><td><h4><i class="fa-share-nodes">:share-nodes:</i></h4><h4>Share</h4></td><td>Copies a shareable link to a Webchat deployment so you can hand off a preview to a teammate</td></tr><tr><td><h4><i class="fa-up-right-from-square">:up-right-from-square:</i></h4><h4>Open in New Tab</h4></td><td>Opens the same preview link in a standalone browser tab</td></tr></tbody></table>

### Cloning and Replacing Agents

The Agents table includes two actions that let you duplicate agents and transfer content between them. Both are available from the **Actions** column on each agent row. For a detailed walkthrough on how to use them see [Version Control](/build/version-control.md).

<table data-column-title-hidden data-view="cards"><thead><tr><th>Title</th><th>Description</th></tr></thead><tbody><tr><td><h4><i class="fa-copy">:copy:</i></h4><h4>Clone Agent</h4></td><td>Create an identical copy of an agent — including workflows, variables, and configurations. Clone within the same Workspace or into a different one.</td></tr><tr><td><h4><i class="fa-arrows-retweet">:arrows-retweet:</i></h4><h4>Replace Agent Content</h4></td><td>Overwrite one agent's content with another's. Use this to promote changes between environments (e.g., Dev to Staging).</td></tr><tr><td><p><i class="fa-code-branch">:code-branch:</i></p><h4>Version Control</h4></td><td>Combine Clone and Replace to set up a Dev → Staging → Production workflow that keeps your live agent safe while you iterate.</td></tr></tbody></table>

### Deleting an Agent

{% hint style="danger" %}
Deleting an agent is permanent. All associated data -including workflows, chat sessions, and surveys- will be also be removed. Ensure you have exported, cloned, or backed up any necessary data before proceeding.
{% endhint %}

1. Go to **Designer > Settings** and click on **Configuration**
2. Click **Delete this agent** under the Danger Zone
3. Type 'DELETE' (uppercase) in the textbox to confirm deletion

<div data-with-frame="true"><figure><img src="/files/aeVeR1PdaCiRW0SoQdb3" alt=""><figcaption></figcaption></figure></div>

### Backups

Backups let you save and restore a complete snapshot of your agent's configuration — including workflows, variables, and settings. The platform does not create backups automatically, so you need to create them manually before making significant changes.

Go to **Designer > Backups** to manage backups for the current agent. Each backup is associated with the timestamp of when it was created, a unique identifier and an optional note.

{% hint style="success" %}
Create a backup before editing prompts, restructuring workflows, or updating variables. If something breaks, you can restore the previous state in one click instead of rebuilding from scratch.
{% endhint %}

#### Manage Backups

Managing backups is straightforward: create new ones, restore to a previous snapshot, or delete backups you no longer need.

{% tabs %}
{% tab title=" Creating a Backup" %}
Click **Create Backup Now**. A dialog prompts you to add an optional note — use it to describe what the backup captures (e.g., `Before prompt rewrite` or `Stable v2`). Click **Create Backup** to confirm.
{% endtab %}

{% tab title="Restoring a Backup" %}
Click the <i class="fa-clock-rotate-left">:clock-rotate-left:</i> icon in the Actions column. A confirmation prompt appears — click **Yes** to proceed.

{% hint style="danger" %}
**Overwrites Current State** Restoring a backup replaces your agent's entire configuration with the saved snapshot. Any changes made after the backup was created are lost.
{% endhint %}
{% endtab %}

{% tab title="Deleting a Backup" %}
Click the delete icon in the **Actions** column and confirm with **Yes**.

{% hint style="danger" %}
**Permanent Action** Deleting a backup cannot be undone. Make sure you no longer need the snapshot before confirming.
{% endhint %}
{% endtab %}
{% endtabs %}

### Additional Settings

You can manage different agent-specific settings under **Designer > Settings**

<details>

<summary><strong>Configuration</strong></summary>

Configure the identity, chat settings and language of your agent

</details>

<details>

<summary><strong>Privacy</strong></summary>

Configure your agent’s chat privacy settings, including data retention and anonymization protocols.

</details>


---

# 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.helvia.ai/build/agents.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.