Assistants¶
An assistant is the primary entity you interact with through the Nodexa API. When you make a request to POST /v1/responses, you specify an assistant by UUID in the model field. The assistant determines which specialist agents handle the request, which tools are available, and how memory and user context are applied.
The model Field¶
In the OpenAI Responses API, model typically refers to an LLM model name (e.g., "gpt-4o"). In Nodexa, model is the UUID of a Nodexa Assistant:
The assistant UUID is an opaque identifier. It does not encode information about the underlying LLM(s) — those details are configured in the Nodexa admin panel and may change without notice.
Where to find your assistant ID
Your Nodexa platform administrator configures assistants and provides you with their UUIDs. You can also find them in the Nodexa admin dashboard under the Assistants section.
What an Assistant Encapsulates¶
An assistant is a configured unit that includes:
| Component | Description |
|---|---|
| Specialist Agents | One or more LLM-backed agents, each with a specific role, system prompt, and capabilities |
| Routing configuration | Rules and an LLM router that decides which specialist agent handles each request |
| Tools | REST API integrations, MCP server connections, knowledge base retrieval, and web search |
| Memory settings | Whether per-user memory is enabled and how it is applied |
| Response style | Tone, language, and formatting preferences |
Capabilities¶
Multi-Specialist Agent Routing¶
A single assistant may back multiple specialist agents. When you send a message, the platform's routing engine selects the most appropriate specialist agent based on the content of the message, user context, and routing rules. This is transparent to the API caller — you always call the same assistant UUID and get the best response from the right specialist agent.
See Specialist Agents for details.
Built-in Tools¶
Administrators configure tools at the assistant level. These may include:
- Knowledge base retrieval — semantic search over documents
- REST API integrations — calling external APIs
- MCP (Model Context Protocol) servers — dynamic tool discovery
- Web search — real-time web search via OpenAI, Claude, or Gemini
You can supplement or override these tools at request time using the tools field. See Tool Precedence.
Per-User Memory¶
When you include x-user-id in your request, the assistant loads relevant memory items for that user and injects them into the context. After the conversation, new memories may be stored automatically. This allows the assistant to remember user preferences, past interactions, and relevant context across sessions.
User Claims¶
User claims provide structured context about the user (e.g., subscription plan, role, language preference). Claims are injected into the assistant's context automatically when x-user-id is provided. The assistant can reference these claims in its responses.
Assistant vs. LLM Model¶
| Aspect | Nodexa Assistant | LLM Model |
|---|---|---|
| Identified by | UUID (asst_...) |
Model name (gpt-4o, claude-3-5-sonnet, etc.) |
| Routing | Multi-specialist agent routing engine | Single model |
| Tools | Configured in admin panel + overridable per-request | Must be provided per-request |
| Memory | Built-in per-user memory | Must be implemented by caller |
| System prompt | Configured per specialist agent | Must be provided per-request |
| Provider | Abstracted — could be OpenAI, Anthropic, Google, or others | Fixed provider |
Multiple Assistants¶
Your Nodexa instance may have multiple assistants, each configured for a different use case. For example:
- A customer support assistant
- A technical documentation assistant
- An internal knowledge base assistant
Each has its own UUID. You can integrate multiple assistants in the same application by switching the model value.
Handover Between Specialist Agents¶
When the active specialist agent determines that a different specialist agent is better suited to handle the current conversation, it can transfer control. This generates a handover event in the SSE stream (or a handover item in the output array for non-streaming requests).
The handover is transparent to the assistant's UUID — you continue using the same model value. The routing engine manages which specialist agent is active.
See Specialist Agents and SSE Events — handover for details.