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.

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, latency, and whether the run succeeded.

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.

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.