RAG-Assistent

Die Plattform bietet drei Wege, aus Treffern eine Antwort zu machen. Sie unterscheiden sich darin, wer den Dialogzustand hält und wie viel Kontrolle Sie über den Prompt haben.

Antwort mit Quellen — /answerCopy Anchor Link

Einmalige Frage, einmalige Antwort, Quellenliste. Der Endpunkt sucht, baut einen Kontext aus den besten Treffern und lässt ein Modell daraus antworten. Erfordert search:read und die Tariffunktion aiAnswer, die in jedem Tarif enthalten ist — auch in Free, dort mit einem kleinen, hart begrenzten Kontingent von 10.000 KI-Token pro Monat (kein Overage: darüber folgt 429 QUOTA_EXCEEDED).

curl -sS -X POST "$AAC_API/indexes/documentation/answer" \
  -H "Authorization: Bearer $AAC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Was kostet der Pro-Tarif und wie viele Suchen sind enthalten?",
    "per_page": 4
  }'

{
	"index": "documentation",
	"answer": "Der Pro-Tarif kostet 29 USD pro Monat und enthält 500.000 Suchen. Darüber hinaus wird jede angefangene 1.000 Suchen mit 50 Cent aus dem Wallet berechnet.",
	"citations": [
		{
			"index": 1,
			"id": "pricing",
			"title": "Preise",
			"url": "https://example.com/pricing",
			"snippet": "Pro kostet 29 USD im Monat und enthält 500.000 Suchen."
		}
	],
	"found": 3,
	"model": "gpt-4o-mini",
	"tokens": 812,
	"took_ms": 1840,
	"request_id": "req_3f5a7c9e1b3d5f7a9c1e3b5d"
}

citations[].index ist die Nummer, die im Antworttext als [1] erscheint — das Modell wird angewiesen, nur daraus zu zitieren. snippet ist der Ausschnitt, auf dem die Aussage beruht.

Verhalten, das Sie kennen sollten:

• Ohne Treffer keine Antwort. Ist found: 0, kommt eine feste Meldung, citations: [] und tokens: 0 — kein Modellaufruf, keine Kosten.
• Ohne OPENAI_API_KEY antwortet der Endpunkt mit 503 AI_NOT_CONFIGURED. Der Assistent unten funktioniert trotzdem, weil er extraktiv arbeitet.
• per_page bestimmt, wie viele Treffer in den Kontext gehen (intern auf 10 begrenzt). Mehr Kontext heißt bessere Antwort und mehr Tokens.
• Kosten werden als ai_tokens gemessen und dem Tarifkontingent belastet.

DialogassistentCopy Anchor Link

Mehrere Fragen zu einem Thema, mit Gedächtnis. Erfordert search:read.

curl -sS -X POST "$AAC_API/indexes/documentation/assistant" \
  -H "Authorization: Bearer $AAC_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"Was kostet Pro?"}'

{
	"conversation_id": "conv_01HZYB7Q2M",
	"answer": "Der Pro-Tarif kostet 29 USD pro Monat.",
	"mode": "llm",
	"model": "gpt-4o-mini",
	"citations": [
		{
			"index": 1,
			"id": "pricing",
			"title": "Preise",
			"url": "https://example.com/pricing",
			"snippet": "Pro kostet 29 USD im Monat …"
		}
	],
	"found": 2,
	"tokens": 640,
	"latency_ms": 1210,
	"request_id": "req_6b8d0f2a4c6e8b0d2f4a6c8e"
}

Die ID kommt zusätzlich im Header x-aac-conversation mit. Die zweite Frage referenziert die erste über conversation_id:

curl -sS -X POST "$AAC_API/indexes/documentation/assistant" \
  -H "Authorization: Bearer $AAC_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"Und ab welcher Menge wird es teurer?","conversation_id":"conv_01HZYB7Q2M"}'

mode sagt, wie die Antwort entstand:

• llm — ein Modell hat aus den Quellen geantwortet (braucht OPENAI_API_KEY).
• extractive — kein Modell verfügbar, deshalb liefert der Assistent eine zusammengesetzte Zusammenfassung der Treffer-Ausschnitte mit Quellenliste. Der Endpunkt funktioniert, der Text ist nur zusammengestellt statt formuliert.

Der Verlauf liegt in der Datenbank; beim nächsten Aufruf geht er als Kontext mit, begrenzt auf die letzten Runden, damit der Prompt nicht unbegrenzt wächst.

StreamenCopy Anchor Link

POST /indexes/{index}/assistant/stream liefert dieselbe Antwort als SSE, damit die ersten Wörter sofort erscheinen.

curl -sS -N -X POST "$AAC_API/indexes/documentation/assistant/stream" \
  -H "Authorization: Bearer $AAC_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"Was kostet Pro?"}'

data: {"type":"citations","payload":{"citations":[...],"conversation_id":"conv_01HZYB7Q2M"}}

data: {"type":"delta","payload":{"text":"Der Pro-Tarif"}}

data: {"type":"delta","payload":{"text":" kostet 29 USD pro Monat."}}

data: {"type":"done","payload":{"conversation_id":"conv_01HZYB7Q2M","tokens":204,"latency_ms":1210}}

Reihenfolge: citations zuerst (damit die Oberfläche Quellen sofort zeigen kann), dann delta-Fragmente, dann done. Ein Fehler mitten im Stream kommt als {"type":"error","payload":{"message":"…"}}, und der Stream endet. Jeder Frame ist eine einzelne data: -Zeile plus Leerzeile — genau das parsen die SDKs.

Threads lesenCopy Anchor Link

curl -sS "$AAC_API/indexes/documentation/assistant" \
  -H "Authorization: Bearer $AAC_KEY"

{
	"conversations": [
		{
			"id": "conv_01HZYB",
			"title": "Was kostet Pro?",
			"messageCount": 2,
			"createdAt": "2026-10-23T10:12:00.000Z",
			"updatedAt": "2026-10-23T10:12:04.000Z"
		}
	]
}

curl -sS "$AAC_API/indexes/documentation/assistant/conv_01HZYB" \
  -H "Authorization: Bearer $AAC_KEY"

{
	"conversation": {
		"id": "conv_01HZYB",
		"messages": [
			{
				"id": "msg_1",
				"role": "user",
				"content": "Was kostet Pro?",
				"created_at": "2026-10-23T10:12:00.000Z"
			},
			{
				"id": "msg_2",
				"role": "assistant",
				"content": "29 USD pro Monat.",
				"citations": [{ "index": 1, "id": "pricing", "title": "Preise" }],
				"created_at": "2026-10-23T10:12:04.000Z"
			}
		]
	}
}

Eine Konversations-ID, die zu einem anderen Index gehört, ergibt 404 CONVERSATION_NOT_FOUND — die Suche ist nach Index eingegrenzt, nicht nur nach Mandant.

Gespräch der Engine — /assistant/nativeCopy Anchor Link

Wenn Sie das Dialogmodell vom Suchdienst selbst nutzen wollen (etwa ein auf Ihre Domäne trainiertes Modell), leitet dieser Endpunkt direkt dorthin weiter. Er braucht ein konfiguriertes Modell oder eine model_id im Body, sonst 503 CONVERSATION_MODEL_NOT_CONFIGURED; ohne Engine 30.0 501 ENGINE_FEATURE_UNSUPPORTED — GET /capabilities zeigt features.conversation.

Welche Modelle konfiguriert sind, verrät:

curl -sS "$AAC_API/indexes/documentation/conversation-models" \
  -H "Authorization: Bearer $AAC_KEY"

Prompt und GrenzenCopy Anchor Link

• Der Prompt ist nicht konfigurierbar. Die Plattform baut ihn aus Frage und den Treffer-Ausschnitten (maximal sechs, je 1.200 Zeichen). Eigenen System-Prompt oder eigene Persona gibt es derzeit nicht.
• Zitate sind Pflicht. Kommt vom Modell nichts Verwertbares, folgt 502 AI_EMPTY_RESULT; ein Anbieterfehler wird 502 AI_UNAVAILABLE.
• Ein language-Feld gibt es nicht. Die Antwortsprache folgt der Frage; die Suche erkennt die Sprache aus dem Text.
• Filter wirken. filter_by im Body schränkt die Treffer ein, aus denen der Kontext gebaut wird.
• Kein Streaming über mehrere Runden. Der Stream liefert eine Antwort; für die nächste Runde starten Sie einen neuen Stream mit conversation_id.
• Kosten laufen über ai_tokens. Jeder Aufruf belastet das Kontingent der Organisation.

Welchen Endpunkt wannCopy Anchor Link

Für alles außer /search gilt: Der Nutzen hängt an der Qualität der Treffer. Ein Assistent über einem schlecht gepflegten Index erfindet keine Inhalte, er zitiert nur schlechte.