useSubagent()

useSubagent turns a parent subagent tool card into { agent, threadId, status }. It does not fetch or watch the child. Mount the child binding's ThreadProvider with that threadId to render the nested transcript.

const Explorer = Pai.agent("explorer");

function ExplorerCard({
  tool,
}: {
  tool: ToolRenderProps<AssistantPai["agents"]["main"], "research">;
}) {
  const subagent = Assistant.useSubagent(tool);
  if (!subagent) return null;
  return (
    <Explorer.ThreadProvider threadId={subagent.threadId}>
      <ChildChat />
    </Explorer.ThreadProvider>
  );
}

Import

const subagent = Assistant.useSubagent(tool);

Signature

function useSubagent<TName extends ToolRendererName<TContract>>(
  tool: ToolRenderProps<TContract, TName>,
): SubagentRef | null;

Parameters

tool: ToolRenderProps<TContract, TName>

Props of the parent subagent tool card.

Returns

A SubagentRef | null.

SubagentRef

agent: string

Roster key the parent model selected.

agentId?: string

Matching createPai registry id, when it can be inferred.

threadId: string

runId?: string

status: "running" | "completed" | "failed" | "cancelled"

Status of the delegation:

running: the child run is in progress.
completed: the child run finished successfully.
failed: the child run or delegation failed.
cancelled: the delegation stopped before completion.

title?: string

resultPreview?: string

error?: { message: string }