Knowledge Bases with Agents

Overview

Knowledge Base integration with Agents enables AI systems to access and query your custom data sources during agent execution. This powerful combination allows agents to ground their responses in your specific domain knowledge, documents, and datasets.

Key Features

Dynamic Knowledge Discovery: Agents can discover available knowledge bases using retrieve_knowledge_bases
Contextual Querying: Query specific knowledge bases with query_knowledge_base based on user queries
Automatic Grounding: Responses are grounded in your custom data sources
Multiple Knowledge Sources: Connect agents to multiple knowledge bases simultaneously

Examples

curl -X POST https://api.orq.ai/v2/agents/run \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "book-assistant",
  "role": "Book Assistant",
  "description": "A friendly agent who is connected to knowledge bases and helps people",
  "instructions": "Help the user with their questions please. First use retrieve_knowledge_bases to see what knowledge sources are available, then query_knowledge_base to find relevant information.",
  "settings": {
    "max_iterations": 5,
    "max_execution_time": 600,
    "tools": [
      {
        "type": "current_date"
      },
      {
        "type": "retrieve_knowledge_bases"
      },
      {
        "type": "query_knowledge_base"
      }
    ]
  },
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "What is the coat of arms of the Apafi family?"
      }
    ]
  },
  "model": "anthropic/claude-opus-4-1-20250805",
  "path": "Default/agents",
  "knowledge_bases": [
    {
      "knowledge_id": "01JFT339RR48BW3BKHCY3R3VMH",
      "configuration": {
        "type": "last_user_message"
      }
    }
  ]
}'

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.run(request={
        "key": "book-assistant",
        "role": "Book Assistant",
        "description": "A friendly agent who is connected to knowledge bases and helps people",
        "instructions": "Help the user with their questions please. First use retrieve_knowledge_bases to see what knowledge sources are available, then query_knowledge_base to find relevant information.",
        "settings": {
            "max_iterations": 5,
            "max_execution_time": 600,
            "tools": [
                {
                    "type": "current_date"
                },
                {
                    "type": "retrieve_knowledge_bases"
                },
                {
                    "type": "query_knowledge_base"
                }
            ]
        },
        "message": {
            "role": "user",
            "parts": [
                {
                    "kind": "text",
                    "text": "What is the coat of arms of the Apafi family?"
                }
            ]
        },
        "model": "anthropic/claude-opus-4-1-20250805",
        "path": "Default/agents",
        "knowledge_bases": [
            {
                "knowledge_id": "01JFT339RR48BW3BKHCY3R3VMH",
                "configuration": {
                    "type": "last_user_message"
                }
            }
        ]
    })

    assert res is not None
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.agents.run({
    key: "book-assistant",
    role: "Book Assistant",
    description: "A friendly agent who is connected to knowledge bases and helps people",
    instructions: "Help the user with their questions please. First use retrieve_knowledge_bases to see what knowledge sources are available, then query_knowledge_base to find relevant information.",
    settings: {
      maxIterations: 5,
      maxExecutionTime: 600,
      tools: [
        {
          type: "current_date"
        },
        {
          type: "retrieve_knowledge_bases"
        },
        {
          type: "query_knowledge_base"
        }
      ]
    },
    message: {
      role: "user",
      parts: [
        {
          kind: "text",
          text: "What is the coat of arms of the Apafi family?"
        }
      ]
    },
    model: "anthropic/claude-opus-4-1-20250805",
    path: "Default/agents",
    knowledgeBases: [
      {
        knowledgeId: "01JFT339RR48BW3BKHCY3R3VMH",
        configuration: {
          type: "last_user_message"
        }
      }
    ]
  });

  console.log(result);
}

run();

❗️
Agents should use retrieve_knowledge_bases to discover available knowledge bases before querying them. Guide your agent with instructions like: First use retrieve_knowledge_bases to see what knowledge sources are available, then query_knowledge_base to find relevant information.

📘
To learn more about Knowledge Bases, see Knowledge Bases.