Child invocations

Use startAgentInvocation() when trusted host or parent code must control child Agent work after starting it. Use the Subagents Capability when the active model chooses and awaits delegated work itself.

Start and inspect a child

import { startAgentInvocation } from 'vite-hub/agent'
import researcher from '../agents/researcher'

const child = await startAgentInvocation(researcher, runtimeContext, {
  prompt: 'Compare the two deployment options.',
})

const current = await child.inspect()
if (current.outcome === 'available') {
  console.log(current.invocation.id, current.invocation.status)
}

Every start gets a fresh stable id. inspect() returns an available snapshot or an explicit unavailable outcome. Available lifecycle states are pending, running, completed, failed, and cancelled.

Inline and serverless runtimes may become unavailable after their process ends. Workflow-backed children delegate inspection to their Workflow Run while the returned controller remains available. ViteHub does not add a separate invocation registry or public lookup by id.

Cancel active work

const cancellation = await child.cancel('The parent no longer needs this work.')

if (cancellation.outcome === 'accepted') {
  const latest = await child.inspect()
}

accepted means the runtime accepted the request; inspect again for the observed terminal state. A provider may return unsupported, and terminal invocations return invalid-state.

Respond to provider requests

Check the controller's current support before sending input, then handle the operation result because support can change with lifecycle state.

if (child.support.respond) {
  const result = await child.sendInput(
    { messages: [responseMessage] },
    { mode: 'respond' },
  )
}

Inline provider runtimes accept approval decisions and data-agent-input answers while the matching provider request is pending. Text steering, follow-up turns, and Workflow-backed input remain unsupported until their runtime adapters provide equivalent ordering and lifecycle semantics.

The subagents() Capability uses the same start seam but returns a serializable tool result and waits for the child. The model cannot choose or reuse the trusted child id.