Team Consultation

Team consultation enables the lead agent to delegate tasks to specialist agents. The SDK supports two patterns: one-to-one specialist consultation and parallel team fan-out.

consultSpecialist

Delegates a task to a single specialist agent. The specialist runs as a separate agent instance with its own model and tools, then returns its response to the calling agent.

// Agent calls this tool with:
{
  agentId: 'cto',
  task: 'Evaluate whether we should migrate from PostgreSQL to SurrealDB given our current scale and team expertise.'
}

How It Works

The calling agent invokes consultSpecialist with a target agentId and task description.
A new agent instance is created for the specialist with the conversation history as context.
The specialist streams its response (visible to the user as a nested consultation).
The specialist's full response is returned to the calling agent as a ChatMessage.
The calling agent synthesizes the specialist's input into its own response.

consultTeam

Fans out a task to all team consultation participants in parallel. This is used when the answer benefits from structured executive input across multiple domains.

// Agent calls this tool with:
{
  task: 'Should we pursue enterprise sales or focus on self-serve? Consider product, engineering, finance, marketing, strategy, and mentorship perspectives.'
}

How It Works

The calling agent invokes consultTeam with a task description.
The SDK spawns one agent instance per participant (configured via teamConsultParticipants).
All agents run in parallel with a 90-second timeout.
As each agent completes, a snapshot is yielded with the current state of all participants.
The client renders real-time progress showing each agent's status and response.
Once all agents complete (or timeout/error), the final aggregated result is returned to the calling agent.

Participant Responses

Each participant response includes:

Field	Description
`agentId`	The specialist's agent ID
`agentName`	Display name (e.g., "CTO", "CFO")
`status`	`running`, `complete`, or `error`
`summary`	Extracted text summary of the response
`message`	Full `ChatMessage` (when available)
`error`	Error message (when failed or timed out)

Streaming Progress

consultTeam is implemented as a generator tool that yields intermediate snapshots:

execute: async function* ({ task }) {
  // ... spawn all agents ...

  while (/* agents still running */) {
    yield buildSnapshot(responses) // Intermediate state
  }

  return buildSnapshot(responses) // Final state
}

This enables the client to show a live dashboard of agent responses as they stream in.

Error Handling

Timeout -- each agent has a 90-second timeout via createTimedAbortSignal. Timed-out agents are marked with status error.
Parent abort -- if the parent run is aborted (user stops), all participant agents are cancelled.
Individual failures -- a single agent failing does not block others. The failed agent's response includes an error message, and any partial response it produced is preserved.

Model Output

The team consultation result is converted to a compact text summary for the model context:

CEO: We should focus on self-serve initially to validate PMF before enterprise.
CTO: Engineering team is too small for enterprise integration requirements.
CFO: Self-serve has better unit economics at our current ARR.
CMO: Enterprise requires dedicated marketing budget we don't have.
CPO: Product maturity isn't sufficient for enterprise SLAs yet.
Mentor: Classic sequencing question - nail self-serve first, then expand up-market.

This summary is what the calling agent sees to synthesize its final response.