# Task Agents

Build specialized sub-agents your main agent can hand complex, multi-step work off to.

<Mermaid chart={`sequenceDiagram
    participant U as User
    participant M as Main Agent
    participant T as Task Agent
    U->>M: Complex request
    M->>M: Identifies specialized work
    M->>T: Delegate with inputs
    T->>T: Multi-step reasoning
    T-->>M: Structured output
    M->>U: Final response using task result
`} />

**Path:** Agent Studio → Task Agents

Task Agents are specialized sub-agents that the main agent can hand off complex, multi-step tasks to. Each task agent focuses on a specific workflow, which keeps that reasoning out of the main conversation and lets you tune, version, and test it on its own.

## How a task agent is triggered

The same published task agent can be invoked three ways — they all run the identical versioned, observable skill:

- **From chat.** The main agent delegates automatically mid-conversation when it recognizes the specialized work, as in the diagram above. No code required on your side.
- **From a UI element.** Wire the SDK call to a button, menu item, or any element in your product — for example a "Summarize" button that runs the task agent on the current record and renders the result inline. This is the same `runTask()` call, just driven by a UI handler instead of the chat agent.
- **From the API / your backend.** Call the task agent programmatically as a synchronous AI API, anywhere in your code, and get back trusted text or JSON.

The UI-element and API paths use the same SDK method:

```javascript
foldspace.agent('YOUR-AGENT-API-NAME').runTask({
  taskKey: 'YOUR-TASK-KEY',
  data: 'ANY-STRING-OR-OBJECT'
});
```

Grab the exact snippet from the **Code Snippet** tab. Full parameters, streaming, and caching: [Task Agent API](/reference/task-agent-api/).

## Task agent list

Each row shows:

- **Name** — the task agent's name (e.g., "Material Extractor PDF Agent").
- **API Name** — the programmatic identifier.
- **State** — `Published` or `Draft`.
- **Live version / Latest version** — version numbers; if they differ, an unpublished draft exists.
- **Modified Date** — when the task agent was last edited.

## Create a task agent

Click **Create New** in the top-right. The editor opens with six tabs: **Details**, **Output**, **Evaluation**, **Code Snippet**, **Model**, and **Logs**.

### Details tab

The primary configuration pane:

| Field | Purpose |
| :--- | :--- |
| **API Name** | The programmatic identifier used to call this task agent from the SDK (e.g., `task_agent_api_name`). Auto-generated from the name. |
| **Description** | A short summary of what this task agent does (roughly ~200 characters). |
| **Instructions** | The full behavioral instructions — what it should do, what inputs it expects, and how to format its output. Supports up to **16,000 characters**. |
| **Web Search** | Toggle. When enabled, the task agent can search the web for up-to-date information as part of its reasoning — useful when it needs current data, documentation, or real-world facts. |

The **Generate** button (top-right, with a sparkle ✦ icon) lets you describe what you want the task agent to do in plain English and have Foldspace AI draft the Description and Instructions for you.

### Output tab

Define the structured output schema the task agent should return — useful when downstream code or actions need to consume the result in a predictable format.

### Evaluation tab

Configure automated quality checks on the task agent's output, similar to [Trust Lab evals](/user-guides/trust-lab/). Set up criteria the output must satisfy before being passed back to the main agent.

### Code Snippet tab

Shows the SDK code to invoke this task agent programmatically from your product's backend or frontend.

### Model tab

Choose the underlying AI model for this task agent. Different task agents can run on different models — use a faster, cheaper model for simple lookups and a more capable one for complex reasoning.

### Logs tab

Real-time execution history for this task agent. Each log entry shows the inputs sent, the output returned, the model used, latency, cost, and whether the run succeeded. See [Analyzing and tuning](#analyzing-and-tuning) for how to use it.

## Testing task agents

Exercise a task agent against real inputs before you publish, so you know it behaves:

- **Inspect the input schema.** The editor shows the input schema the task agent expects — the fields, their types, and which are required — so you can see exactly what the main agent (or an SDK call) must pass. Use it to craft representative test inputs.
- **Run and check the output.** Send sample inputs and compare the structured result against the schema you defined in the **Output** tab.
- **Evaluate automatically.** The **Evaluation** tab runs quality checks on the output, the same way [Trust Lab](/user-guides/trust-lab/) evals do — assert the result meets your criteria before it ever reaches the main agent.

## Analyzing and tuning

The **Logs** tab is the task agent's observability surface. Every run records its **inputs and output**, the **model** that handled it, **latency**, and **cost** — so you can see which task agents are slow or expensive and tune them.

- **Switch models.** The **Model** tab moves a task agent to a different model. Put simple lookups on a faster, cheaper model and reserve a more capable one for heavy reasoning, then compare latency and cost in the logs after the switch.
- **Built-in caching.** Task agents cache results automatically — a repeated run with the same inputs returns from cache instead of re-running the model, cutting both latency and cost. Developers can tune this per call; see [Cache options](/reference/task-agent-api/#cache-options).

## Publishing

Use the **Publish** button in the top-right when the task agent is ready. The version number increments on each publish. Task agents must be **Published** before the main agent can delegate to them.

:::note[Example]
A "Material Judge Agent" might review an invoice and determine whether materials are eligible — a multi-step reasoning task better handled by a dedicated sub-agent than inline in a conversation.
:::

## Coding examples

Call a published task agent from your own frontend or backend with `runTask()`:

- [Task Agent API](/reference/task-agent-api/) — full `runTask()` parameters, streaming, structured output, and cache options.
- [Example: analyze report data](/guides/task-agent-analysis/) — a worked example that runs a task agent over report data and renders the result.