Skip to main content
When you send a message in a chat thread, the agent:
  1. Receives your message
  2. Decides which tools to use (search, read, browse, etc.)
  3. Calls those tools to retrieve information from your knowledge base
  4. Synthesizes a response with inline citations linking back to specific content
  5. Streams the response in real-time to your browser
The agent is not a simple RAG (Retrieval-Augmented Generation) pipeline. It is an agentic loop — the LLM autonomously decides what to do next, can make multiple tool calls, reason about results, and iterate until it has enough information to answer.

​
How It Works

​
Two-Phase Pattern

The key architectural insight is the two-phase pattern:
  • Phase 1 (steps 1-6): The API immediately returns 202 Accepted and your browser opens a streaming connection. This is non-blocking — you see a “thinking” indicator immediately.
  • Phase 2 (steps 7-14): The agent runs asynchronously. As it thinks, searches, and writes, events are published in real-time to your browser.

​
Request Lifecycle

Here is the complete flow from sending a message to receiving a response:
  1. You send a message — the API creates a record of your message and starts a durable workflow
  2. Your browser opens a stream — a Server-Sent Events (SSE) connection receives real-time updates
  3. The agent processes your request:
    • Fetches your conversation history for context
    • Decides which tools to use (search, read, browse, etc.)
    • Calls tools to retrieve information from your knowledge base
    • May call multiple tools iteratively until it has enough information
    • Generates a response with inline citations
  4. You see the response stream — text appears token-by-token, with tool calls visible as thinking steps
  5. The response is saved — the complete message with citations is persisted to the database
  6. The stream closes — your browser receives a completion signal
If your connection drops during streaming, you can reconnect and either resume the stream or fetch the completed message.

​
Agent Capabilities

​
Tools

The agent has 8 specialized tools for interacting with your knowledge base: See the Tools page for detailed documentation on each tool.

​
Citations

Every fact the agent states from your knowledge base is backed by a citation linking to the specific chunk of content. The agent writes responses with inline markers that are resolved into structured citation objects with source paths and quotes. Multiple citation formats are supported:
  • [chunk_id] — standard format
  • [chunk_id1, chunk_id2] — multiple citations
  • Other formats are normalized automatically

​
Conversation History

The agent maintains conversation context across messages in a thread. It loads your recent message history (up to 10 messages) and uses it to understand follow-up questions and maintain context.

​
Real-Time Streaming

As the agent works, you see:

​
Reliability

​
Error Handling

Errors are handled gracefully across three categories:

​
Always-Persist Guarantee

No matter what goes wrong, the agent always persists a response to the thread. Even if the LLM completely fails, you see a “Something went wrong. Please try again.” message rather than the UI getting stuck in a loading state.

​
Concurrent Run Protection

Only one agent run can be active per thread at a time. If you send a message while the agent is already processing, you receive a 409 Conflict response.

​
Configuration

​
Agent Behavior

​
Streaming Events

The streaming protocol follows an industry-standard pattern:

​
API Endpoints

​
Send a message

Sends your message and triggers agent processing. Returns 202 Accepted immediately with a workflow_id. Request:
Response (202):

​
Stream the response

Opens an SSE connection to receive real-time agent output. Query parameters: If you provide last_message_id, you must also provide last_entry_id. If the message is no longer streaming when you reconnect, you receive a message_not_streaming event and can fetch the completed message via REST.

​
Glossary