Agent Architecture

​

What the Agent Does

1. Authenticates — obtains credentials to act on your behalf, ensuring all knowledge base access respects your permissions
2. Loads context — fetches your conversation history to understand follow-up questions
3. Runs the AI agent — the LLM decides which tools to use, retrieves information, and generates a response
4. Streams in real-time — as the agent thinks and writes, events are published to your browser immediately
5. Saves the response — the complete message with citations is persisted to the database
6. Closes the stream — sends completion signals so your browser knows the response is finished

​

Agent Capabilities

• LLM communication — handles model requests, response parsing, and retries
• Streaming — provides real-time event iteration as the model generates output
• Conversation history — maintains context across messages in a thread
• Tool execution — the agentic loop where the LLM decides to call tools, receives results, and continues reasoning
• Structured output — validates agent responses

​

Request Processing

1. Initialize — prepare the agent and generate a unique message ID
2. Authenticate — obtain a token to access the API on behalf of the user
3. Load context — fetch the user’s message and recent conversation history (up to 10 messages)
4. Open the stream — publish a message_start event
5. Run the agent — the AI agent processes the request with streaming:
   • Each text token is published as a text_delta event
   • Each tool call and result is published as a step event
   • The agent sends heartbeats every 10 seconds to prove it is still working
6. Process citations — resolve inline chunk references into structured citation objects
7. Save the message — persist the complete response with citations and tool steps
8. Close the stream — publish message_end and done events; clear the streaming flag

​

Streaming Protocol

​

Event Lifecycle

message_start -> text_start -> text_delta* -> text_end -> (citations)? -> message_end -> done

message_start -> text_start -> text_delta* -> text_end
             -> step(call) -> step(result)
             -> text_start -> text_delta* -> text_end
             -> message_end -> done

​

Reconnection

• If the message is still streaming, the client resumes from where it left off with missed events replayed
• If the message is no longer streaming, the client receives a message_not_streaming event and can fetch the complete message via REST

​

Conversation History

​

API Endpoints

​

Send a Message

• Returns 409 Conflict if the agent is already processing a message on this thread

{
  "input_text": "What is the retention policy?"
}

{
  "workflow_id": "agent-{thread_id}"
}

​

Stream the Response

​

Security Model

1. It obtains a token scoped to your user identity and tenant
2. All knowledge base access goes through the API’s authorization layer
3. The agent can only see and search content you have permission to access