Skip to main content

​
Knowledge API

The Knowledge API provides access to agent knowledge and the shared knowledge library. Agents maintain persistent memory across sessions — they write plans, decisions, journals, research notes, and other entries that survive container restarts. The shared knowledge library lets users curate collections of documents that agents can search during inference.

​
Agent Knowledge (AKM)

​
Entry Types

Agents organize knowledge into typed entries:

​
Agent Tools

Agents interact with knowledge through built-in tools available in their sandboxed runtime:

​
AKM Token Refresh

Agent containers authenticate to the Knowledge service using short-lived JWTs (Ed25519-signed). The agentbox runtime runs an automatic token refresh loop that renews the AKM token before its 1-hour expiry, so agents maintain uninterrupted access to knowledge services across long-running sessions.

​
Access Model

  • Users see knowledge from agents they own.
  • Admins see knowledge from all agents.
  • Read-only via API — only agents write knowledge through internal services.
Knowledge search uses a hybrid approach combining PostgreSQL full-text search (FTS) with pgvector semantic similarity:
  • FTS — tsvector/GIN index with ts_rank ordering and ts_headline snippets for keyword matching.
  • Vector similarity — 1536-dimensional embeddings generated by text-embedding-3-small (via LiteLLM) during ingestion. Stored in pgvector and queried with cosine similarity.
  • Hybrid ranking — Results from both methods are combined using reciprocal rank fusion for better recall than either method alone.

​
Endpoints

​
Shared Knowledge Library

The shared knowledge library lets users curate collections of documents that agents can retrieve during inference. Collections support text/markdown content and web page ingestion.

​
Concepts

  • Collection — A named group of sources with a visibility setting (private or shared). Private collections are visible only to the owner’s agents; shared collections are available to all agents.
  • Source — A document within a collection. Source types: text (direct text/markdown) and web_page (fetched from a URL with SSRF protection).
  • Ingestion pipeline — Sources are chunked (~500 tokens/chunk, ~50 token overlap, paragraph and heading boundaries), embedded via text-embedding-3-small, and indexed for both FTS and vector search.

​
Endpoints

​
Quality Metrics

The stats endpoint provides aggregate quality metrics for the shared knowledge library:
  • Search metrics — Total searches, zero-result rate, average duration, breakdown by requester type (user vs. agent).
  • Ingest health — Job counts by status (pending, processing, completed, error), error rate, average processing time.
  • Source breakdown — Counts by status and source type.
  • Corpus summary — Total collections, sources, documents, and chunks.
Metrics support a since time-range filter (e.g., 24h, 7d, 30d). All data is aggregate-only — no raw query text or user identifiers are exposed.

​
Authentication

All endpoints require a valid Keycloak JWT bearer token with the user role:
See the auto-generated endpoint pages below for request/response details.