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

# Subagent Task

> Detailed documentation for the subagent tool.

The `subagent` tool allows an AI assistant to delegate complex, specialized, or multi-step tasks to a dedicated sub-agent. The sub-agent runs in its own isolated session with its own context, tools, and skills, and then returns a final result back to the parent agent.

This is particularly useful for breaking down large problems, utilizing specialized agents (e.g., a "Data Analyst" or "Code Reviewer" agent), or running tasks that require a specific set of tools without cluttering the main session's context.

## When to Use This Tool

Use the `subagent` tool when you need to:

* **Delegate Specialized Tasks:** Hand off a specific task to an agent that is pre-configured with the right system prompt, tools, and skills for that job.
* **Isolate Context:** Run a complex task in a separate session so the intermediate steps and tool outputs don't pollute the main conversation history.
* **Parallelize Work:** (When used in conjunction with parallel tool execution) Spawn multiple sub-agents to handle different parts of a problem simultaneously.

## Input Parameters

The tool accepts the following parameters:

| Parameter          | Type               | Required | Description                                                                                                                                      |
| :----------------- | :----------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`           | `string`           | Yes      | The detailed instruction or task for the sub-agent.                                                                                              |
| `agent_id`         | `string`           | No       | Optional ID (UUID) of a specific assistant/agent to use. If not provided, a default generic agent is used.                                       |
| `tools`            | `array of strings` | No       | Optional list of tool names the sub-agent should have access to. These will be merged with the assistant's default tools.                        |
| `skills`           | `array of strings` | No       | Optional list of skill IDs the sub-agent should have access to. These will be merged with the assistant's default skills.                        |
| `model`            | `string`           | No       | Optional model to use for the sub-agent. If not provided, it falls back to the assistant's default model or the system default (e.g., `gpt-4o`). |
| `external_user_id` | `string`           | No       | Optional external user ID to propagate context and permissions.                                                                                  |
| `document_ids`     | `array of strings` | No       | Optional list of document IDs to attach to the sub-session. These will be merged with the assistant's default documents.                         |
| `workspace_ids`    | `array of strings` | No       | Optional list of workspace IDs to attach to the sub-session. These will be merged with the assistant's default workspaces.                       |

## Output Structure

The tool returns an object containing the final result produced by the sub-agent.

```json theme={null}
{
  "result": "The final text response or result generated by the sub-agent after completing its task."
}
```

## Example Usage

### Scenario: Delegating Data Analysis

**Input:**

```json theme={null}
{
  "prompt": "Analyze the attached Q3 financial data and summarize the key revenue trends. Focus on month-over-month growth.",
  "agent_id": "uuid-for-data-analyst-agent",
  "tools": ["python_interpreter", "read_document"],
  "document_ids": ["uuid-for-q3-financial-data"]
}
```

**Result:**
The `subagent` tool will spawn a new session using the specified Data Analyst agent. The sub-agent will use the `python_interpreter` and `read_document` tools to analyze the data. Once finished, it will use its internal `submit_result` tool to return the final summary.

```json theme={null}
{
  "result": "Based on the Q3 financial data, revenue grew by 5% in July, 8% in August, and 12% in September. The key driver for this growth was the new enterprise software tier..."
}
```

## Advanced Features

### 1. Context and Resource Propagation

When spawning a sub-agent, you can pass specific `document_ids` and `workspace_ids`. The system will automatically verify the user's access to these resources and attach them to the sub-session. If no specific resources are requested, the sub-agent will inherit the default files and workspaces configured for that specific `agent_id`.

### 2. Tool and Skill Merging

The `tools` and `skills` arrays provided in the input are merged with the default tools and skills of the target assistant. This allows you to dynamically grant temporary capabilities to a sub-agent for a specific task.

### 3. The `submit_result` Mechanism

Internally, the sub-agent is instructed to use a special `submit_result` tool when it has completed its task. This ensures that the sub-agent explicitly defines what the final output should be, rather than the system having to guess from the conversation history.

### 4. Intermediate Results and Monitoring

While the sub-agent is processing the task, it runs in a separate, isolated session. The tool emits a data event (`SUB_AGENT_STARTED`) containing the `sub_session_id`. Clients can use this `sub_session_id` to monitor the sub-agent's progress, view intermediate messages, and see tool executions in real-time before the final result is submitted. If you want to render the sub-agent's activity in a UI, you should use the standard session endpoints to fetch the information for that `sub_session_id` and connect to its associated stream.

### 5. Recursion Prevention

To prevent infinite loops, the `subagent` tool cannot call itself recursively. Even if the `subagent` tool is explicitly requested in the `tools` array or is a default tool of the target assistant, it will be automatically removed from the sub-agent's available tools.