Skip to lesson

AnthropicClaude Certified Architect – Foundations2026-101.3 Configure subagent invocation, context passing, and spawning

Delegate through the Agent tool

Completed by the knowledge check

Learning objective

Enable coordinator delegation with the exam guide’s Task tool (Agent in current Claude Code/Agent SDK), distinguish it from separate application-driven API calls, and account for tool-access configuration.

Core idea

For an architect embedding the Agent SDK, delegation means the coordinator invokes the harness’s Agent tool to launch a subagent. It is different from your application making two separate Messages API calls and combining their responses. Both designs can divide work, but the component that launches the work and manages its context is different.

The product documentation names the spawning tool Agent, accepts Task as an alias, and distinguishes available tools from pre-approved calls. allowedTools does not define the available tool set, and the permissions documentation identifies Agent as a tool that does not ask before running. Configure availability and approval as separate mechanisms. The exam guide words the requirement differently; Where the exam guide differs covers how to read it.

See 1.1.5 for execution-loop ownership and 1.3.1 for specialist definitions. Here you configure the path between a coordinator’s decision and a real subagent invocation.

How it works

Expose the spawning tool to the coordinator

Both Agent SDKs have a top-level tools option that accepts a list of tool names or the Claude Code preset, {"type": "preset", "preset": "claude_code"}. In Python, this is ClaudeAgentOptions.tools; in TypeScript, it is options.tools. If you supply an explicit list for a coordinator, include Agent when it must delegate. A definition in agents identifies a specialist but does not substitute for the coordinator’s access to the spawning tool.

This TypeScript configuration shows availability and pre-approval separately:

const options = {
  tools: ["Agent", "Read", "Grep", "Glob"],
  allowedTools: ["Agent", "Read", "Grep", "Glob"],
  agents: {
    "document-reviewer": {
      description: "Reviews supplied documents for evidence gaps.",
      prompt: "Report supported findings and missing evidence.",
      tools: ["Read", "Grep", "Glob"],
    },
  },
};

Supply options to query() alongside a prompt that assigns work to document-reviewer. The top-level tools list controls the coordinator’s tool configuration. The nested tools list controls the specialist’s tools. They are separate lists for separate execution contexts; the reviewer does not need its own spawning tool merely to receive delegated work.

The allowedTools entry mirrors the documented subagent examples, but it is a pre-approval entry, not what creates delegation capability. Python uses top-level allowed_tools for approval and disallowed_tools for deny rules, alongside tools for availability. The specialist still uses AgentDefinition.tools. Copy identifiers from the language you are using rather than substituting TypeScript casing into ClaudeAgentOptions.

Separate permission rules from tool availability

The SDK applies TypeScript allowedTools / disallowedTools, or Python allowed_tools / disallowed_tools, as allow and deny rules. A bare disallowedTools: ["Agent"], or Python disallowed_tools=["Agent"], removes the spawning tool from the request. An approval entry cannot restore a tool removed by a deny rule or omitted from an explicit tool configuration.

Conversely, leaving Agent out of allowedTools does not by itself remove it. Tools not listed there remain available, subject to the applicable permission behavior. permissionMode: "dontAsk" denies calls that would require an approval prompt, but the documentation says tools such as Agent that do not ask before running still run. Use availability controls when the requirement is “this coordinator must not spawn,” rather than an approval list that only looks restrictive.

Keep approval policy separate from the specialist’s role restrictions. Auto-approving Read for the main session does not mean the worker should inherit command execution or file editing. Narrow the worker through AgentDefinition.tools, as in 1.3.1. Diagnose a failure by checking the coordinator’s tool pool, deny rules, and the specialist definition, rather than rewriting a clear task prompt first.

Verify that delegation happened

Claude selects specialists from their descriptions, and the SDK documentation recommends naming a specialist in the prompt when you need it invoked explicitly. To observe the invocation, inspect assistant tool_use blocks for name: "Agent". A natural-language statement that a reviewer checked the documents is not invocation evidence.

Verify the requested specialist as well: check input.subagent_type === "document-reviewer" on the spawning block. An Agent call without subagent_type uses the built-in general-purpose subagent by default, even when you define no custom agents. A spawning-tool name alone therefore does not prove that the named reviewer ran.

The SDK subagent guide documents a compatibility detail: tool_use blocks use Agent, while the system:init tools list uses Task. Releases before Claude Code v2.1.63 also emitted Task in tool_use blocks. If your monitoring spans those versions, match both names rather than concluding that delegation failed because a single spelling was absent.

Messages from inside a subagent’s execution context include parent_tool_use_id. That field lets you associate worker activity with the parent invocation. It is a correlation mechanism, not evidence that the worker inherited the parent’s conversation; see 1.3.3 for context passing.

Key distinctions and trade-offs

Harness delegation versus application scheduling: In the Agent SDK, the coordinator requests Agent and the harness runs the subagent. In a Messages API design, the application submits separate client.messages.create(...) requests, chooses each request’s system, messages, and tools, and combines the responses itself. The API is stateless; the application supplies each request’s conversation history.

The two designs differ in the component that launches the work.

The two designs differ in the component that launches the workIn the Agent SDK, the coordinator requests Agent and the harness runs the subagent. In a Messages API design, the application submits separate requests and combines the responses itself. The harness launches the work in one design; the application launches it in the other.Messages API designAgent SDKrequests AgentrunsApplicationSeparate requestSeparate requestCombines theresponsesCoordinatorHarnessSubagent

Built-in tool versus application-defined tool: The harness’s Agent has spawning behavior. Giving a custom Messages API tool the name Task does not import that harness behavior. Your application must implement the custom tool’s execution and return its result through the tool-use protocol; see 1.1.2.

Selection instructions versus capability configuration: Naming a specialist directs the coordinator toward it. An available spawning tool makes delegation executable. Neither an agent name nor a prompt can override a removed tool.

Choose the SDK when you want its agent harness to own specialist execution. Choose application-driven calls when your application must schedule independent requests and construct their inputs directly. Do not infer shared context or permission behavior across those two designs merely because both use the word “agent.”

Architecture / decision scenario

A developer-productivity service embeds the Agent SDK and asks a coordinator to have document-reviewer inspect migration notes before answering. The team supplies only Read, Grep, and Glob in top-level tools, but adds Task to allowedTools. The coordinator answers directly, and the logs contain no spawning tool_use block.

Adding an approval entry did not add the missing capability. You include Agent in the coordinator’s explicit tools list, check that no bare deny rule removes it, and keep the reviewer’s nested tools read-only. You name document-reviewer in the assignment and verify an Agent or compatible Task invocation with input.subagent_type === "document-reviewer" in the message stream.

A second service implements the same business workflow with two client.messages.create(...) calls: one review request and one synthesis request. That service can succeed without an Agent SDK spawning tool. Its application owns passing the review evidence into synthesis and constructing tool histories. The reviewer’s system prompt and task input are request fields, rather than an AgentDefinition launched by a coordinator tool call.

The deciding question is which component actually launches the specialist. Inspect that path before changing permissions or assuming the Messages API automatically provides SDK delegation.

Common exam traps

  • Treating Task and Agent as unrelated delegation mechanisms.
  • Assuming allowedTools creates or restricts the tool pool.
  • Expecting dontAsk to block every unlisted tool.
  • Confusing top-level coordinator tools with a specialist’s tools list.
  • Taking a textual claim of delegation as proof of an invocation.
  • Treating an Agent call without subagent_type, which uses general-purpose by default, as proof that the named specialist ran.
  • Assuming separate Messages API calls inherit Agent SDK orchestration.
  • Rewriting the coordinator’s prompt or the specialists’ descriptions when the coordinator’s tool set lacks Agent.

Where the exam guide differs

Note:

The exam guide calls the spawning mechanism “the Task tool” and requires that “allowedTools must include “Task”” for a coordinator to invoke subagents. Claude Code renamed the tool Agent in v2.1.63 and still accepts Task(...) references in settings and agent definitions as aliases. In the SDK, allowedTools adds allow rules: an unlisted tool stays available, and a call to Agent needs no approval in default mode. What removes delegation is an explicit top-level tools list without Agent, or a bare disallowedTools entry. In an exam item, read “Task in allowedTools” as “the coordinator has the spawning tool”. When an item’s coordinator never delegates although its specialists are defined, the cause is the missing spawning tool: an option that rewrites the coordinator’s prompt, the specialists’ descriptions, or the model choice leaves that cause in place.

What to remember

Use Agent for harness-managed spawning and recognize the exam guide’s Task name. Configure availability separately from pre-approval, inspect deny rules, and verify actual tool invocations. Application-driven API calls are a different execution path whose scheduling and context construction belong to your application.

Knowledge check

References