defineSubagentTool()

A subagent is another agent in the same createPai app. The parent exposes a tool; the model picks a child and a task; PAI runs that child on a hidden thread.

You do not write inputSchema or execute. The model calls this with { agent, task }.

export const research = defineSubagentTool({
  id: "research",
  agents: {
    explorer: {
      agent: explorerAgent,
      description: "Read-only research over workspace documents",
    },
  },
});

Import

import { defineSubagentTool } from "@pai/core";

Signature

function defineSubagentTool<TId extends string>(
  config: {
    id: TId;
    description?: string;
    contextSchema?: z.ZodType;
    agents: Record<string, SubagentToolAgentConfig>;
  },
): ToolDefinition<...>;

Parameters

config: object

id: string

Stable definition id. Different child rosters need different ids.

agents: Record<string, SubagentToolAgentConfig>

Roster the model selects from.

agent: AgentDefinition

Child agent. Also register it on createPai({ agents }).

description: string

When the parent should pick this child.

task?: (input) => SendInput

identity?: (input) => Identity

thread?: { id?, visibility?, title? }

description?: string

Override the built-in delegation prompt. Usually omit.

contextSchema?: z.ZodType

Model input

agent: string

Roster key.

task: string

threadId?: ThreadId

description?: string

HTTP access: { explorer: "read" } hides the child from browser starts. The parent can still spawn it in-process.

The parent tool waits for the child run to complete, then returns its assistant text and child thread/run IDs. If the child run fails, or is stopped while the parent keeps running, the call fails: the parent model reads that the sub-agent (by its roster key) failed or was stopped, the child's threadId (with a hint to continue it after a failure), and the child run's error when it is more than PAI's generic run failure. When the parent run is stopped, the call ends as cancelled like any other. The subagent ToolData channel reports running and terminal status while the child executes.

Returns

A ToolDefinition.