Manage Knowledge

Attach Knowledge to your AgentOS instance

The AgentOS control plane provides a simple way to manage your Knowledge bases. You can add, edit, and delete content from your Knowledge bases directly through the control plane.

You can specify multiple Knowledge bases and reuse the same Knowledge instance across different Agents or Teams as needed.

Prerequisites

Before setting up Knowledge management in AgentOS, ensure you have:

The example below uses PostgreSQL (with pgvector) and OpenAI embeddings. Swap in any supported vector database or embedder.

Example

The example below attaches multiple Knowledge bases to AgentOS and populates them with content from different sources.

agentos_knowledge.py
from textwrap import dedent

from agno.db.postgres import PostgresDb
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.knowledge.knowledge import Knowledge
from agno.os import AgentOS
from agno.vectordb.pgvector import PgVector, SearchType

db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"
documents_db = PostgresDb(
    db_url,
    id="agno_knowledge_db",
    knowledge_table="agno_knowledge_contents",
)
faq_db = PostgresDb(
    db_url,
    id="agno_faq_db",
    knowledge_table="agno_faq_contents",
)

documents_knowledge = Knowledge(
    name="documents_knowledge",
    vector_db=PgVector(
        db_url=db_url,
        table_name="agno_knowledge_vectors",
        search_type=SearchType.hybrid,
        embedder=OpenAIEmbedder(id="text-embedding-3-small"),
    ),
    contents_db=documents_db,
)

faq_knowledge = Knowledge(
    name="faq_knowledge",
    vector_db=PgVector(
        db_url=db_url,
        table_name="agno_faq_vectors",
        search_type=SearchType.hybrid,
        embedder=OpenAIEmbedder(id="text-embedding-3-small"),
    ),
    contents_db=faq_db,
)

agent_os = AgentOS(
    description="Example app with AgentOS Knowledge",
    # Add the knowledge bases to AgentOS
    knowledge=[documents_knowledge, faq_knowledge],
)


app = agent_os.get_app()

if __name__ == "__main__":
    documents_knowledge.insert(
        name="Agno Docs", url="https://docs.agno.com/llms-full.txt", skip_if_exists=True
    )
    faq_knowledge.insert(
        name="Agno FAQ",
        text_content=dedent("""
            What is Agno?
            Agno is a framework for building agents.
            Use it to build multi-agent systems with memory, knowledge,
            human in the loop and MCP support.
        """),
        skip_if_exists=True,
    )
    # Run your AgentOS
    # You can test your AgentOS at: http://localhost:7777/

    agent_os.serve(app="agentos_knowledge:app")

Screenshots

The screenshot below shows how you can access and manage your different Knowledge bases through the AgentOS interface:

AgentOS Knowledge management interface

Knowledge ID

Each Knowledge instance registered with AgentOS gets a deterministic knowledge_id. It is a SHA256 hash of {db_id}:{knowledge_table}:{name} (contents-database id, knowledge_table name, instance name), formatted as a UUID-shaped string (8-4-4-4-12 hex). If the instance has no name, AgentOS substitutes knowledge_{db_id}. The same inputs always produce the same ID, so it is stable across restarts.

Use knowledge_id in API calls to target a specific Knowledge instance:

# List content sources
curl http://localhost:7777/knowledge/{knowledge_id}/sources

# Browse files in an S3 source
curl "http://localhost:7777/knowledge/{knowledge_id}/sources/{source_id}/files?prefix=reports/"

# Upload content
curl -X POST "http://localhost:7777/knowledge/content?knowledge_id={knowledge_id}" \
  -F "file=@report.pdf" \
  -F "name=Q4 Report"

For uploads from S3, GCS, SharePoint, GitHub, or Azure Blob (including source_params and S3 file browsing), see Remote Content.

Finding your Knowledge ID

The root /config endpoint returns the full AgentOS configuration, including a knowledge.knowledge_instances list with the ID, name, and database details for every registered Knowledge instance:

curl http://localhost:7777/config | jq '.knowledge.knowledge_instances'
[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "documents_knowledge",
    "db_id": "agno_knowledge_db",
    "table": "agno_knowledge_contents"
  },
  {
    "id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
    "name": "faq_knowledge",
    "db_id": "agno_faq_db",
    "table": "agno_faq_contents"
  }
]

Backward compatibility

If you have a single Knowledge instance, you can omit knowledge_id from API calls. AgentOS will route to it automatically. For multiple instances, you can also use the db_id query parameter, but knowledge_id is preferred as it uniquely identifies the instance even when multiple instances share the same database.

Best Practices

  • Separate Knowledge by Domain: Create separate Knowledge bases for different topics (e.g., technical docs, FAQs, policies)
  • Consistent Naming: Use descriptive names for your Knowledge bases that reflect their content
  • Regular Updates: Keep your Knowledge bases current by regularly adding new content and removing outdated information
  • Separate Vector Tables: Use different table names for vector storage to avoid conflicts
  • Content Organization: Use the name parameter when adding content to make it easily identifiable
  • Use metadata for filtering and searching: Add metadata to your content to make it easier to find and filter

Troubleshooting