OpenAI-compatible API

SAG exposes an OpenAI Chat Completions-compatible endpoint for every Agent. Standard clients can call SAG like a model while retaining the same knowledge scope, streamed answers, and source citations as the built-in interface.

Endpoint

POST /api/v1/openai/{agent_id}/chat/completions
Authorization: Bearer <SAG_JWT>
Content-Type: application/json

This is a self-hosted interface, not a public cloud API operated by the SAG project. Point the base URL to your own SAG instance.

Non-streaming request

curl -s http://localhost:8000/api/v1/openai/<AGENT_ID>/chat/completions \
  -H "Authorization: Bearer <SAG_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What does this material explain?"}
    ]
  }'

The response preserves the standard chat.completion structure and adds sag.citations:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "..."},
      "finish_reason": "stop"
    }
  ],
  "sag": {
    "citations": [
      {"chunk_id": "...", "source_id": "...", "title": "..."}
    ]
  }
}

A standard client that does not recognize the extension ignores sag, preserving basic compatibility.

Streaming request

Set "stream": true in the request body. The service returns incremental chunks over SSE. The client must consume events until completion instead of waiting for one complete JSON response.

{
  "messages": [{"role": "user", "content": "Summarize the retrieval architecture"}],
  "stream": true
}

Agent and knowledge scope

The agent_id in the URL selects the SAG Agent. Its saved source bindings become the default knowledge scope. To use a different scope, create or update another Agent instead of fabricating sources in the client.

Answers require an LLM, an Embedding model, and ready documents. If the endpoint is reachable but models are not configured, the service returns a structured error instead of generating an ungrounded answer.

Client configuration

Most OpenAI-compatible clients require three values:

SDKs append paths to a base URL differently. The final request must resolve exactly to /chat/completions. Verify it with curl before configuring another client.