Runs represent individual message exchanges with an agent. Each run streams events via Server-Sent Events (SSE) to provide real-time updates on the agent’s progress.
Send Message (Streaming)
Send a message to an agent session and receive a streaming response.
POST /v1/sessions/{session_id}/messages
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Accept: text/event-stream
Session ID (e.g., ses_xyz789)
Message to send to the agent
{
"prompt": "What's the weather like in San Francisco?"
}
Server-Sent Events (SSE)
The response is a stream of Server-Sent Events. Each event has a type and data field.
event: message.delta
data: {"content":"Hello"}
event: tool.start
data: {"tool":"get_weather","input":{"city":"San Francisco"}}
event: run.completed
data: {"duration_ms":1234}
Run Event Types
message.delta
Streamed text chunk from the agent’s response.
Text content to append to the response
{
"type": "message.delta",
"data": {
"content": "The weather in San Francisco is "
}
}
Name of the tool being invoked
Input parameters passed to the tool
{
"type": "tool.start",
"data": {
"tool": "get_weather",
"input": {
"city": "San Francisco",
"units": "celsius"
}
}
}
Tool execution time in milliseconds
{
"type": "tool.end",
"data": {
"duration_ms": 342
}
}
run.started
Run has started processing.
Example:
{
"type": "run.started",
"data": {}
}
run.completed
Run finished successfully.
Total run duration in milliseconds
Whether the agent hit its maximum turn limit
Message explaining the turn limit if reached
{
"type": "run.completed",
"data": {
"duration_ms": 5432,
"max_turns_reached": false
}
}
run.failed
Run encountered an error.
Error message describing what went wrong
{
"type": "run.failed",
"data": {
"error": {
"message": "Agent exceeded memory limit"
}
}
}
run.cancelled
Run was cancelled by the user or system.
Empty object or cancellation metadata
{
"type": "run.cancelled",
"data": {}
}
status
General status update from the agent.
Status information (structure varies)
heartbeat
Keep-alive event to prevent connection timeout.
TypeScript Example
import { parseSSEStream } from './streaming'
const response = await fetch(
'https://api.superserve.ai/v1/sessions/ses_xyz789/messages',
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({ prompt: 'Hello!' })
}
)
for await (const event of parseSSEStream(response)) {
if (event.type === 'message.delta') {
process.stdout.write(event.data.content ?? '')
} else if (event.type === 'tool.start') {
console.log(`\nUsing tool: ${event.data.tool}`)
} else if (event.type === 'run.completed') {
console.log(`\nCompleted in ${event.data.duration_ms}ms`)
}
}
Using the SDK
The Superserve SDK handles SSE parsing automatically:
import Superserve from '@superserve/sdk'
const client = new Superserve({ apiKey: 'YOUR_API_TOKEN' })
// Streaming
const stream = client.stream('my-agent', {
message: 'Hello!'
})
for await (const chunk of stream.textStream) {
process.stdout.write(chunk)
}
// One-shot (waits for full response)
const result = await client.run('my-agent', {
message: 'Hello!'
})
console.log(result.text)
Error Responses
If the request fails before streaming starts, you’ll receive a standard HTTP error response:
Common Errors:
| Status | Message |
|---|
| 401 | Not authenticated |
| 404 | Session not found |
| 422 | Invalid message format |
| 429 | Rate limit exceeded |
run.failed events. 