Skip to main content

Chat Tutorial

Goal: Send an authenticated chat request, understand streaming events, and find the turn receipt for a completed response.

Prerequisites: Quickstart completed and the platform running.

Time: About 5 minutes.

1. Start a Conversation​

Open http://localhost and send a message. Responses stream as server-sent events, so the UI can render tokens, tool activity, artifacts, blocking decisions, and the final answer as they arrive.

The API request shape is:

{
  "messages": [
    {"role": "user", "content": "Give me a short platform overview."}
  ],
  "tenant_id": "default",
  "user_id": "admin",
  "session_id": "optional-session"
}

The legacy single message field is not the current chat contract.

2. Watch Tool Activity​

Ask a question that benefits from tools, for example:

Search the internal knowledge base for deployment runbook notes.

The UI receives typed stream events such as tool_call, tool_result, trace_update, artifact, blocked, token, and done. Reasoning or trace UI should summarize model-visible progress; it should not present hidden reasoning internals as raw text.

3. Upload a File​

Use the file upload control in the chat UI, then ask a question about the file. The platform indexes the document through the knowledge service and the agent can call knowledge_search when answering. Search events are also recorded as turn events when the request has a turn context.

4. Start a New Session​

Use New Chat to start a fresh session. Session history and long-lived memory are separate:

  • Session messages belong to that conversation.
  • Memory stores durable preferences, corrections, and project facts.
  • Knowledge stores uploaded documents and wiki pages.

5. Retrieve the Receipt​

Completed turns return receipt metadata when turn sealing is enabled. You can retrieve proof material through the audit service:

curl "http://localhost:8080/v1/receipts/{turn_id}" \
  -H "X-Tenant-ID: default"
curl "http://localhost:8080/v1/receipts/{turn_id}/proof" \
  -H "X-Tenant-ID: default"

Use the Audit Trail Reference for verification details.

Next Steps​

Read the Chat Reference for the full request/response contract and stream event types.