subagents

# Subagent Dispatch Skill

Use `call_subagent` to delegate tasks to other agents, and `wait_for_subagents` to collect results from background runs.
These tools are Code Mode tools: run the snippets below with `run_sdk_snippet`, where `sdk.tool.call(...)` is available.

Agent is the generic technical term. Crew is the product term for a marketplace custom Agent presented as a digital employee (数字员工). Users may say Agent, 智能体, digital employee, 数字员工, or Crew. Do not call built-in Agents Crew.

## When To Use

Delegate when at least one is true:

- The task is large enough to benefit from an isolated execution context
- Multiple independent tasks can run in parallel
- You need a specialized agent type (read-only explore, shell-heavy work)

Do not delegate when:

- The task is small and can be done directly
- The work requires constant access to the current conversation state
- Multiple sub-agents would write to the same file with no merge plan
- You cannot summarize the full context into a self-contained prompt

**Depth limit**: sub-agents cannot call `call_subagent`. Only the root agent may dispatch.

## Selecting The Target Agent

- If the user provides a built-in name, local `.agent` name, or `SMA-...` code, skip discovery and call that Agent directly.
- If the target is unknown or must be selected by capability, call `find_agents` to search marketplace custom Agents presented as Crew digital employees.
- Built-in Agents (`magic`, `explore`, `shell`, `search`) do not require discovery.

```python
from sdk.tool import tool

result = tool.call("find_agents", {
    "keywords": [
        "<core term in the user's language>",
        "<distinct variant in the user's language>",
        "<optional common term from another relevant language>",
    ],
    "query": "<the user's complete requirement in the user's language>",
    "limit": 5,
})
print(result.content)
```

- `keywords`: build the complete recall list before the first call and submit it once.
  - Infer the user's language from the request and use that language for the main terms.
  - Usually use two to four high-information words or phrases with distinct recall value.
  - Add a term from another language only when candidate names, common industry terminology, or the target search source is likely to use it. English is often useful for product names and technical acronyms, but it is not mandatory.
  - English requests normally use English terms only. Japanese requests should use Japanese terms first, Korean requests should use Korean terms first, and the same rule applies to every other language. Preserve relevant terms when the user mixes languages.
  - Prefer short terms that may appear directly in candidate names.
  - For short names or acronyms, include common case forms when search sources may treat them differently.
  - Do not enumerate case forms for ordinary phrases, add overlapping synonyms only to increase the count, put the complete requirement in an item, or call `find_agents` once per keyword.
- `query`: the user's complete requirement in the user's language, used to select more relevant candidates.
- `limit`: choose based on the task. The default is `5`; valid values are `1` through `20`.

Read `result.content`, choose by `code`, `name`, and `description`, then pass the selected `SMA-...` code directly as `call_subagent.agent_name`.
Do not automatically split or retry the same search intent when no candidates are returned.

### Browsing The Full Agent List

When the user asks which Agents are available rather than asking to get something done, browse instead of searching: pass `keywords=[]` and `query=None`. Results come back in a stable order with no relevance filtering, so the first entry is not necessarily the best fit.

```python
from sdk.tool import tool

result = tool.call("find_agents", {
    "keywords": [],
    "query": None,
    "limit": 20,
})
print(result.content)
```

Read `has_more` and `next_page` from `result.content`. To read the following page, keep every other argument unchanged and set `page` to `next_page`. Page order is stable and pages do not overlap.

Do not page through the whole directory to see everything — each page costs context. Read further pages only when the user asked for the complete list, or when the current page contains no suitable Agent.

Paging is not available for keyword search, because ranked order is not stable across pages. When a keyword search returns too few results, raise `limit` or change `keywords` instead.

## Tool: call_subagent

```python
from sdk.tool import tool

result = tool.call("call_subagent", {
    "agent_name": str,       # required; use "" when fork=True to inherit the current Agent
    "agent_id": str,         # required; base ID for new sessions, exact final ID when resuming
    "task_label": str,       # required; user-facing label in the user's language
    "prompt": str,           # required
    "model_id": str,         # optional, defaults to inheriting the caller's model
    "background": bool,      # optional, default False
    "fork": bool,            # optional, default False
    "resume": bool,          # optional, default False
})
```

### agent_name

Target agent to call. Accepted values:

- Built-in names or aliases: `magic`, `explore`, `shell`, `search`, `ppt`, `data_analysis`
- Marketplace custom Agent codes returned by `find_agents`, such as `SMA-...` (Crew digital employees)
- Local `.agent` filenames

For marketplace custom Agent codes, `call_subagent` prepares the Agent automatically before dispatch.

Built-in types:

- `magic`: general-purpose, full tool access (web, files, code). Use for complex multi-step tasks.
- `explore`: read-only. Searches files, reads code, answers structural questions. Cannot modify anything.
- `shell`: shell command specialist. Runs scripts, installs deps, performs system operations.
- `search`: web research specialist. Searches the web and reads pages to gather external information. Cannot modify local files.