Specialist Agents¶

A specialist agent is an LLM-backed agent within an assistant. Each specialist agent has a specific role, system prompt, set of tools, and area of expertise. When you call an assistant, the routing engine selects the appropriate specialist agent to handle the request.

What is a Specialist Agent?¶

Think of an assistant as a team of experts. Each expert (specialist agent) handles a specific domain:

A Billing Specialist Agent answers questions about invoices, payments, and subscriptions
A Technical Support Specialist Agent helps with product configuration and troubleshooting
A General Assistant Specialist Agent handles greetings, small talk, and routing

When a user sends a message, the routing engine reads the message and conversation context, then directs it to the specialist agent best equipped to respond.

Specialist Agent Routing¶

The routing process happens automatically and is transparent to API callers. You always call the same assistant UUID — the platform selects and invokes the right specialist agent internally.

The routing engine uses a combination of:

Stage A: Keyword and pattern matching (fast, low-cost)
Stage B: Embedding-based semantic similarity (accurate, cached)
Stage C: LLM-based routing decision (high confidence for ambiguous cases)

The routing decision is based on the current message content, conversation history, and any instructions you provide in the request.

Specialist Agent Handover¶

When the active specialist agent determines it cannot best serve the current request — either because the topic has shifted or the user's need falls outside its domain — it may perform a handover to a more appropriate specialist agent.

Handover in Streaming Responses¶

A handover event appears in the SSE stream as a response.output_item.added event with type: "handover":

{
  "type": "response.output_item.added",
  "item": {
    "type": "handover",
    "from_specialist": "General Assistant",
    "to_specialist": "Billing Specialist",
    "reason": "User is asking about an invoice from last month"
  }
}

Handover in Non-Streaming Responses¶

In non-streaming responses, handover items appear in the output array:

{
  "id": "resp_01234567-89ab-cdef-0123-456789abcdef",
  "status": "completed",
  "output": [
    {
      "type": "handover",
      "from_specialist": "General Assistant",
      "to_specialist": "Billing Specialist",
      "reason": "User is asking about an invoice from last month"
    },
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "I've connected you with our Billing Specialist Agent who can help with your invoice."
        }
      ]
    }
  ]
}

Handover Fields¶

Field	Type	Description
`type`	`"handover"`	Identifies this output item as a handover notification
`from_specialist`	`string`	Display name of the specialist agent that was active
`to_specialist`	`string`	Display name of the specialist agent that took over
`reason`	`string`	Human-readable explanation of why the handover occurred

Handling Handovers in Your UI¶

Handover events are informational — you do not need to take any action. However, you may want to surface them to users or use them for analytics:

for await (const event of stream) {
  if (event.type === 'response.output_item.added') {
    if (event.item.type === 'handover') {
      // Optionally show a status message in the UI
      console.log(
        `Transferring to ${event.item.to_specialist}: ${event.item.reason}`
      );
    }
  }

  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta);
  }
}

Direct Handover by Name¶

If your application needs to direct a request to a specific specialist agent — bypassing the routing engine — you can specify the specialist agent by name in the instructions field:

{
  "model": "YOUR_ASSISTANT_ID",
  "input": "I need help with my invoice #INV-2024-001",
  "instructions": "Route this request directly to the Billing Specialist Agent."
}

Availability depends on configuration

Direct handover by name is supported when the platform's routing engine is configured to respect instruction-based routing. Contact your Nodexa administrator to confirm.

Specialist Agent Context¶

Each specialist agent has its own system prompt and personality configured in the Nodexa admin panel. However, some context is shared across all specialist agents in an assistant:

User memory — loaded at the start of each request and available to all specialist agents
User claims — available to all specialist agents
Conversation history — full history is available regardless of which specialist agent handled earlier turns

Identifying the Active Specialist Agent¶

The response does not currently expose which specialist agent handled the request in the top-level response object. To track which specialist agent was used, monitor the response.output_item.added events in the stream for handover items, or inspect your Nodexa admin panel's conversation logs.