Knowledge Base

Config agents can search through uploaded documents and connected workspace knowledge bases using the built-in search_knowledge_base tool. This enables retrieval-augmented generation (RAG), where the agent finds relevant information from your documents before generating a response.

How Knowledge Base Works

When KB sources or workspace connections are configured, the ConfigurableAgent automatically registers a search_knowledge_base tool with the LLM. During task execution, the model can call this tool to:

1. Search across all configured sources (uploaded files, workspace spaces, projects).
2. Return the most relevant text chunks with source attribution.
3. Use the retrieved information to generate accurate, grounded responses.

The agent's system prompt includes guidelines to cite sources when using KB information: [Source: filename].

KB Sources

KB sources connect the agent to files uploaded directly to it. Each source is defined with:

@dataclass
class KBSourceConfig:
    type: str = "agent"     # Currently only "agent" type
    agent_id: str = ""      # Agent name whose uploaded files to search

The agent_id typically matches the agent's own name, meaning it searches files uploaded to this agent. To configure:

{
  "kb_sources": [
    {
      "type": "agent",
      "agent_id": "my-research-agent"
    }
  ]
}

Uploading Files

Upload documents through the Society AI dashboard or API. Supported files are processed, chunked, and embedded for vector search. The KB indexer handles:

• Text extraction from documents
• Chunking into searchable segments
• Vector embedding generation
• Index storage for fast retrieval

Workspace Connections

Workspace connections let your agent search knowledge from broader organizational spaces and projects. This is useful when your agent needs access to shared team knowledge rather than just its own uploaded files.

@dataclass
class WorkspaceConnection:
    type: str                       # "space" or "project"
    space_id: str                   # Workspace space identifier
    name: str = ""                  # Display name for the connection
    project_id: Optional[str] = None  # Optional project within the space

Connecting a Space

A space connection gives the agent access to all documents within a workspace space:

{
  "workspace": [
    {
      "type": "space",
      "space_id": "ws-abc-123",
      "name": "Engineering Docs"
    }
  ]
}

Connecting a Project

A project connection narrows the scope to a specific project within a space:

{
  "workspace": [
    {
      "type": "project",
      "space_id": "ws-abc-123",
      "project_id": "proj-def-456",
      "name": "API Documentation"
    }
  ]
}

The search_knowledge_base Tool

When KB is configured, the agent receives this tool:

async def search_knowledge_base(
    query: str,       # Natural language search query
    top_k: int = 5,   # Number of results (default 5, max 20)
) -> Dict[str, Any]:

The tool sends a request to the KB search endpoint with:

• agent_name -- The agent's identifier (for resolving its KB sources).
• org_id -- Organization context for workspace connections.
• query -- The natural language search query.
• top_k -- Maximum number of results to return.

The KB search service resolves the agent's configured sources from the database, fans out searches across all sources, merges results, and returns the most relevant chunks.

Search Results

The tool returns a JSON object with:

• Text chunks ranked by relevance.
• Source file names for citation.
• Metadata about which sources were searched.

The agent then uses these results to generate an informed response, citing sources as instructed by the system prompt.

Combining KB Sources and Workspace

You can configure both KB sources and workspace connections. The search tool fans out across all configured sources and returns merged, ranked results:

{
  "kb_sources": [
    {
      "type": "agent",
      "agent_id": "product-support"
    }
  ],
  "workspace": [
    {
      "type": "space",
      "space_id": "ws-support-docs",
      "name": "Support Documentation"
    },
    {
      "type": "project",
      "space_id": "ws-engineering",
      "project_id": "proj-api-docs",
      "name": "API Reference"
    }
  ]
}

In this example, the agent searches across its own uploaded files, the Support Documentation space, and the API Reference project -- returning the most relevant results from any source.

Tips

1. Write search-friendly queries -- The system prompt instructs the agent to search with natural language queries, not keywords. The vector search works best with descriptive queries.

2. Upload focused documents -- Smaller, focused documents produce better search results than large, general-purpose files.

3. Use workspace connections for shared knowledge -- If multiple agents need access to the same documentation, connect them to a shared workspace rather than uploading duplicate files.

4. Set appropriate top_k -- The default of 5 results works well for most cases. For complex questions that might require information from multiple documents, the agent may increase this to 10-20.