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

# Agent overview

> What a Tela Agent is, how the two harnesses differ, what you find on the Agent page and how an Agent goes from idea to production

An **Agent** is an autonomous AI worker. You describe its purpose, declare the inputs it receives and the outputs you expect, and give it skills, helpers, reference files and integrations. The Agent then decides which steps to take and completes the task on its own, in a single run or in a conversation.

This section goes through every part of an Agent in detail. If you have never created one, start with [Your first Agent](https://docs.tela.com/en/creating-your-first-agent.md) and come back here.

## When to use an Agent

| If your task… | Use |
| - | - |
| Can be done with one instruction, such as extracting fields from a document | [Canvas](https://docs.tela.com/en/creating-your-first-canvas.md) |
| Has several steps you can draw in advance | [Workflow](https://docs.tela.com/en/creating-your-first-workflow.md) |
| Has steps you can't define in advance, needs external services, or is a conversation | **Agent** |

An Agent costs more per run than a Canvas and is harder to make predictable than a Workflow. Reach for it when the path depends on what the Agent finds along the way. A Workflow can still use an Agent for one of its steps (see [Running an Agent and getting results](https://docs.tela.com/en/agent/running-and-results.md)).

## The running example

The pages in this section build the same Agent: a **contract assistant** for a legal team. It receives a contract file and a question, reads the contract, answers the question and flags clauses that look risky. Its outputs are `answer` (a text) and `risky_clauses` (a list of texts). You will see it in every page so the pieces connect.

## The two harnesses

The harness is the engine that runs the Agent. You choose it in the **New agent** dialog, and it can't be changed after the Agent is created.

| | **Lightweight · Tela** | **Claude Code · Anthropic** |
| - | - | - |
| Described in the dialog as | Faster, works with models from any provider | More thorough for complex work, with Claude models |
| Models | Models from several providers | Claude models |
| Extra settings | Its own page layout, with **Settings**, **References** and a **Tools** group (**Super search**, **Document parsing**, **Splitter** and published Workflows or Canvases as tools) | **Advanced settings** next to the model: thinking, reasoning effort, prompt cache and parallel subagents |

A simple rule: start with **Lightweight** when the task is well scoped, latency matters or you want a model from a specific provider. Pick **Claude Code** when the Agent has to work through long, open-ended tasks with many files, skills and subagents.

![New agent dialog with the Project selector and the two harness options](https://mintcdn.com/meistrari/IBJhAp-onVS37l80/images/agent/new-agent-dialog.png?fit=max\&auto=format\&n=IBJhAp-onVS37l80\&q=85\&s=40bf389a4865661fc61ed677d4bf619f)

## Anatomy of the Agent page

Like a Canvas, the Agent page has **Craft**, **Test** and **Usage** experiences in the top center. These three stay in English in every language.

**Header.** The breadcrumb shows the Workspace, the Project and the Agent title (click it to rename). The `…` menu next to the title has **Connect via API** (once published), **Schedule**, **Make public**, **Agent Credentials** (admins), the template actions (admins), **Rename** and **Delete**. On the right you find the branch selector (`main` by default), the Tela CLI button, **Version History**, **Share link** and the **Publish** button.

**Left sidebar.** The **Craft** experience is organized in sections:

* **Purpose**: the instructions the Agent follows, and the model it uses
* **Inputs**: the variables the Agent receives on each run, as text or files
* **Outputs**: the structured result you expect back, if any
* **Skills**: reusable instructions the Agent loads when a task needs them
* **Subagents**: helpers your Agent can delegate parts of the work to
* **Files**: reference documents the Agent can read while it works
* **Integrations**: external services the Agent can call without ever seeing their credentials

This is the layout of a Claude Code Agent. A Lightweight Agent has its own sidebar, described in [The Lightweight Agent page](https://docs.tela.com/en/agent/purpose-and-model.md#the-lightweight-agent-page).

**Center.** The editor for the selected section.

**Right panel.** **Test your agent**: fill in the **Variables**, send a message or click **Run**, and watch the Agent work. See [Testing an Agent](https://docs.tela.com/en/agent/testing.md).

![Agent page in the Craft experience with the sidebar sections, the Purpose editor and the Test your agent panel](https://mintcdn.com/meistrari/IBJhAp-onVS37l80/images/agent/craft.png?fit=max\&auto=format\&n=IBJhAp-onVS37l80\&q=85\&s=3714bad4ba9579b83ad973273b8186dd)

## Lifecycle

**1. Create it in a Project**

From the **Dashboard**, click **Agent**. In the **New agent** dialog, choose the Project, choose the harness and click **Continue**. Then pick a template or click **Start from scratch**. Agents are always created inside a Project, so there is no Draft step.

**2. Craft**

Write the [Purpose and pick the model](https://docs.tela.com/en/agent/purpose-and-model.md), declare [Inputs and Outputs](https://docs.tela.com/en/agent/inputs-and-outputs.md), then add [Skills, Subagents and Files](https://docs.tela.com/en/agent/skills-subagents-and-files.md) and [Integrations](https://docs.tela.com/en/agent/integrations-and-credentials.md) as the task requires.

**3. Test**

Run it in the **Test your agent** panel, then turn good runs into test cases in the **Test** experience. See [Testing an Agent](https://docs.tela.com/en/agent/testing.md).

**4. Publish**

Click **Publish**. The published version is what the API, Workflows, schedules and tasks run; the test panel keeps running your latest changes. See [Publishing and versions](https://docs.tela.com/en/agent/publishing-and-versions.md).

**5. Run it where the work happens**

Call it from your systems with **Connect via API**, add it as a step of a Workflow, schedule it or create tasks for it. See [Running an Agent and getting results](https://docs.tela.com/en/agent/running-and-results.md).

> [!NOTE]
>
> Agent creation is enabled per Workspace. If you don't see the **Agent** option on your Dashboard, contact your Tela team.

## How an Agent is stored

Every change you make to an Agent is saved as a new version, and the **Version History** lets you view or restore any of them. Your latest changes live on the `main` branch, which is the draft you test; the version you publish is what runs in production. You can also create other branches to try changes without touching `main`, and merge them later.

> [!NOTE]
>
> **For developers.** An Agent is a git repository. Each save is a commit, and the commit hash is the version ID (shown as `VER-` followed by its first seven characters). `main` HEAD is the draft, the published commit is production. You can work on the repository locally with the Tela CLI; see [Publishing and versions](https://docs.tela.com/en/agent/publishing-and-versions.md#working-locally-with-the-tela-cli).

## In this section

> **[Purpose and model](https://docs.tela.com/en/agent/purpose-and-model.md)**
>
> Write the instructions, mention inputs, skills, subagents and files, choose the model

> **[Inputs and outputs](https://docs.tela.com/en/agent/inputs-and-outputs.md)**
>
> Declare what the Agent receives and the shape of what it returns

> **[Skills, subagents and files](https://docs.tela.com/en/agent/skills-subagents-and-files.md)**
>
> Give the Agent reusable know-how, helpers and reference documents

> **[Integrations and credentials](https://docs.tela.com/en/agent/integrations-and-credentials.md)**
>
> Let the Agent call external services and other Tela resources safely

> **[Testing](https://docs.tela.com/en/agent/testing.md)**
>
> Try the Agent in a conversation, build test cases and read the run history

> **[Publishing and versions](https://docs.tela.com/en/agent/publishing-and-versions.md)**
>
> Versions, the main branch, publishing, restoring and sharing

> **[Running and results](https://docs.tela.com/en/agent/running-and-results.md)**
>
> Use the Agent from a Workflow, the API and tasks, and read its results


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.