Routes and Events
This page documents the route inventory exposed by AI Mastra Bridge and how it implements the io.Intelligence Agent Protocol on top of Mastra.
Use Agent Protocol as the canonical contract reference. This page focuses on the Mastra-specific implementation view.
Route Inventory
The bridge currently registers ten routes.
| Method | Path | Purpose |
|---|---|---|
POST | /run | Starts a protocol streaming run |
POST | /runs/:runId/tool-calls/:toolCallId/result | Submits one frontend tool result back to an active run |
GET | /agents | Lists available agents |
GET | /agents/:agentId | Returns one agent |
POST | /threads | Creates a thread |
GET | /threads | Lists threads |
GET | /threads/:threadId | Returns one thread |
PATCH | /threads/:threadId | Updates a thread |
DELETE | /threads/:threadId | Deletes a thread |
GET | /threads/:threadId/messages | Returns thread messages |
When a custom prefix is configured, that prefix is prepended to each path.
Example with the default prefix:
POST /io-bridge/runPOST /io-bridge/runs/:runId/tool-calls/:toolCallId/resultGET /io-bridge/agentsGET /io-bridge/threads/:threadId/messages
Streaming Route
POST /run
This is the most important bridge endpoint. It accepts a run request, calls the Mastra agent runtime, and streams protocol events over Server-Sent Events.
The bridge translates Mastra stream chunks into the AG-UI-based event subset used by the protocol so frontend clients can work with a consistent event model.
Protocol Event Translation
The bridge emits event categories such as:
- run lifecycle events
- text streaming events
- tool call lifecycle events
- step lifecycle events
Common Event Types
| Event Type | Meaning |
|---|---|
RUN_STARTED | Run lifecycle start |
RUN_FINISHED | Run finished successfully |
RUN_ERROR | Run failed |
TEXT_MESSAGE_START | Assistant text message started |
TEXT_MESSAGE_CONTENT | Text delta chunk |
TEXT_MESSAGE_END | Assistant text message ended |
TOOL_CALL_START | Tool call began |
TOOL_CALL_ARGS | Tool call argument delta |
TOOL_CALL_END | Tool call argument stream ended |
TOOL_CALL_RESULT | Tool result became available |
STEP_STARTED | Execution step started |
STEP_FINISHED | Execution step finished |
Mastra-to-Protocol Mapping
| Mastra Chunk Type | Protocol Event(s) |
|---|---|
text-start | TEXT_MESSAGE_START |
text-delta | TEXT_MESSAGE_CONTENT |
text-end | TEXT_MESSAGE_END |
tool-call-input-streaming-start | TOOL_CALL_START |
tool-call-delta | TOOL_CALL_ARGS |
tool-call-input-streaming-end | TOOL_CALL_END |
tool-call | TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END |
tool-result | TOOL_CALL_RESULT |
step-start | STEP_STARTED |
step-finish | STEP_FINISHED |
finish | RUN_FINISHED |
error | RUN_ERROR |
Frontend Tool Result Reporting
The bridge supports frontend-executed tools without requiring a second /run request:
- the agent emits a tool call
- the frontend executes the tool after
TOOL_CALL_END - the frontend posts the result to
/runs/:runId/tool-calls/:toolCallId/result - the bridge resolves the pending proxy tool
- Mastra emits
TOOL_CALL_RESULTand continues the same run
This matters for assistant clients that integrate tools outside the Mastra backend itself while still relying on Mastra memory and the normal tool loop.
Server Tool Result Capture
The bridge also accounts for server-side tools registered directly with Mastra agents.
Because Mastra does not always emit tool-result chunks consistently, the bridge captures server tool results and emits TOOL_CALL_RESULT events when needed. This helps frontend clients observe a cleaner and more predictable tool lifecycle.
Thread and Message Routes
The thread routes expose a frontend-friendly thread API:
- create a thread before a conversation begins
- list threads for a resource
- fetch one thread
- rename or update thread metadata
- delete a thread
- retrieve thread messages with pagination-style parameters such as
limitandoffset
These routes let the frontend use a stable thread contract without depending on Mastra-specific REST details.
Practical Notes
- memory-backed thread behavior depends on at least one Mastra agent having memory configured
- without memory, stateless streaming can still work, but thread CRUD cannot behave as a persistent thread system
- custom auth and request policy are typically added through host-app middleware around the registered routes