> ## 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.

# Running an Agent and getting results

> Use a published Agent as a Workflow step, from your own systems through the API, in tasks and on a schedule, and read the values it returns

Once published, an Agent can be run from several places. This page covers each one and how to get the values out, using the contract assistant of the [running example](https://docs.tela.com/en/agent/overview.md#the-running-example), which returns `answer` and `risky_clauses`.

## What a result looks like

The result of a run depends on the [Outputs](https://docs.tela.com/en/agent/inputs-and-outputs.md#outputs) of the Agent:

* **No attributes**: the Agent answers in free text (Markdown). You read it, or pass it on as a text.
* **Attributes**: the Agent returns a JSON object with exactly those attributes. For the contract assistant:

```json theme={null}
{
  "answer": "The agreement can be terminated by either party with 30 days' written notice (clause 12.1): \"Either Party may terminate this Agreement upon thirty (30) days prior written notice…\"",
  "risky_clauses": [
    "9.2 – Unlimited liability of the Customer for indirect damages",
    "14.3 – Automatic renewal for successive 24-month periods unless notice is given 180 days in advance"
  ]
}
```

Every attribute is a value you can read by name wherever the result goes: a Workflow step, your code, a task. Keep attribute names stable once other systems depend on them; renaming `risky_clauses` breaks every consumer.

## As a step of a Workflow

A Workflow can run an Agent as one of its steps, so the Agent's judgment sits inside a process you drew in advance: receive the contract, run the assistant, route the contract to a senior lawyer when `risky_clauses` is not empty, otherwise generate the summary document.

In the Workflow, add the **Existing Agent** module (*Add an existing Agent from your Organization*). Click **Select Agent** and pick yours; the list marks each Agent as **Published** or **Unpublished**. Then click **Assign Inputs**: the panel lists the **Inputs from Agent** on one side and the **Workflow Variables** on the other, and you bind each Agent input to a Workflow variable or to the output of a previous step. Required inputs that are still unmapped are highlighted.

**View Agent** opens the Agent inside the Workflow context: a banner at the top reads **Open inside workflow** with the Workflow's name and shows **Assign Inputs** with a counter of mapped inputs, the selectors next to each input let you bind them from there, and **Back to Workflow** returns you to the Workflow.

In the following steps, type `@` to reference the output of the Agent step, the same way you reference any previous step; with structured Outputs, `answer` and `risky_clauses` are the fields of that output. The Agent inherits the credentials of the Workflow (see [Credentials](https://docs.tela.com/en/credentials.md#using-credentials-in-agents)).

![Existing Agent step in a Workflow with the Assign Inputs panel mapping contract and question](https://mintcdn.com/meistrari/M2w7BduKZAFA1Sbx/images/workflow/existing-agent.png?fit=max\&auto=format\&n=M2w7BduKZAFA1Sbx\&q=85\&s=6564130132ad9ff59e9fd4293f23dbe6)

> [!NOTE]
>
> The step always runs the **published** version of the Agent, never your unpublished changes on `main`. Publishing a new version of the Agent changes what every Workflow that uses it does from the next run on.

## From the API

Once the Agent is published, the `…` menu next to its title shows **Connect via API**. The dialog gives you the **Agent ID** and three ready-to-copy requests. Use the exact URL shown there: Agents run on a dedicated API, and the dialog already fills in the Agent ID and the inputs you declared.

![Connect via API dialog with the Agent ID and the Run agent snippet](https://mintcdn.com/meistrari/IBJhAp-onVS37l80/images/agent/connect-api.png?fit=max\&auto=format\&n=IBJhAp-onVS37l80\&q=85\&s=195a7e030901fcc7930597988a9033d6)

**Run agent** starts a new session, or continues one when you include its `sessionId`. The request body has a `message`, the `inputSchema` with one entry per declared input, and optional `environmentVariables`:

```json theme={null}
{
  "message": "Can the customer terminate early, and what should we worry about?",
  "inputSchema": [
    { "type": "file", "name": "contract", "vaultRef": "vault://…", "filename": "services-agreement.pdf" },
    { "type": "text", "name": "question", "content": "Can the customer terminate early?" }
  ],
  "environmentVariables": {}
}
```

The call returns right away with a `sessionId`; the Agent works in the background.

**Get session** (*Poll this endpoint to check execution status and retrieve results*) returns the state of the session and, when it has finished, the result: the JSON object above, or the text. **End session** closes a conversation you no longer need.

> [!NOTE]
>
> **For developers.** A file input is a reference to a file in your Vault (`vault://…`), with an optional display name. Executions are validated against the declared inputs: an unknown name, a type mismatch or a missing required input returns 400. A successful run settles in the `waiting_messages` status, not `completed`: the session is idle and ready for a follow-up message, which is a success. Running an unpublished Agent returns 400 `Agent has no published version`. Read the result from the last assistant turn of the session.

## As tasks

Tasks let several people hand work to an Agent and review the results, the way a [Workstation](https://docs.tela.com/en/workstation/workstation.md) does for a Canvas. Agent tasks are created through the task API with the Agent's ID: there is no App to deploy.

Send a `POST /task` with `sourceType: "agent"`, the `agentId` and up to 100 tasks, each with a `name`, its `rawInput.variables` named after the Agent's inputs, and optional `tags`:

```json theme={null}
{
  "sourceType": "agent",
  "agentId": "2f1c7c1e-6b7a-4e0e-9d5a-1b2c3d4e5f60",
  "tasks": [
    {
      "name": "Acme services agreement",
      "rawInput": {
        "variables": {
          "contract": { "vaultRef": "vault://…", "filename": "acme-services-agreement.pdf" },
          "question": "Can the customer terminate early?"
        }
      },
      "tags": ["acme", "q3-renewals"]
    }
  ]
}
```

Each task starts as `created`, moves to `running`, then to `validating` when the output is ready and awaits review, and to `completed` once approved; `failed` and `cancelled` are terminal. List an Agent's tasks with `GET /task?agentId=…` (this filter can't be combined with `promptApplicationId`), read one with `GET /task/{id}` and approve or edit it with `PATCH /task/{id}`; for Agent tasks, an edited `outputContent` replaces the stored output as is. The result of a task is the same JSON object as above, and the task also records the `agentSessionId` of the run. See the [Task API reference](https://docs.tela.com/api-reference/task/post-task.md).

> [!NOTE]
>
> There is no page in Tela where Agent tasks are listed and reviewed like Workstation tasks. Plan to read and approve Agent tasks through the API.

> [!NOTE]
>
> **For developers.** File values of an Agent task are `{ vaultRef, filename }`, one file per variable. Agent tasks don't support rerun, undo approval, promotion to a test case, analytics or versions.

## On a schedule

In the `…` menu next to the title, **Schedule** runs the Agent by itself at set times, recurring or once. Schedules always run the published version, so publishing changes what the next scheduled run does. An Agent must be published before it can be scheduled; each scheduled run appears in **Usage** like any other session. See [Schedules](https://docs.tela.com/en/schedules/overview.md) for frequencies, time zone and history.

## Reading results after the fact

Every run, whatever started it, is listed in the **Usage** experience with its status, cost and a **Run details** view showing the timeline and the result. See [Usage: the run history](https://docs.tela.com/en/agent/testing.md#usage-the-run-history). A run in **Usage** can be shared by link with teammates who have access to the Agent.

> [!NOTE]
>
> Agents don't have the **Deploy App** option that Canvases and Workflows have in their publish dialog. To give a team a form-like interface for an Agent, run it as a step of a Workflow and [deploy that Workflow as an App](https://docs.tela.com/en/workstation/creating-apps.md).


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