Agent Studio

Task Agents

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:

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.

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

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.

Coding examples

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

Task Agent API — full runTask() parameters, streaming, structured output, and cache options.
Example: analyze report data — a worked example that runs a task agent over report data and renders the result.