Knowledge Base & Context Sources¶

This guide explains how to provide agents with context and knowledge beyond their base system prompt.

Overview¶

Ag2Trust provides multiple ways to inject context into your agents:

All context is assembled by the backend per-request and injected into the agent's effective system prompt. This keeps agents stateless and allows KB changes to take effect immediately.

Context Scoping¶

Resources can be attached to different scopes, allowing inheritance and override:

┌─────────────────────────────────────────────────┐
│  Organization (Customer-wide)                    │  ← Lowest precedence
│  └── Team                                        │
│      └── Agent Type                              │  ← Highest precedence
└─────────────────────────────────────────────────┘

Precedence rules (later overrides earlier):

1. Organization - Applies to all agents in your organization
2. Team - Applies to all agents in a specific team
3. Agent Type - Applies to agents of a specific type

For variable sets, variables from higher-precedence scopes override lower-precedence ones. For documents, all attached documents from applicable scopes are included.

Built-in Variables¶

Platform-provided variables that are resolved at request time. These are opt-in per agent type.

Available Variables¶

Enabling Built-in Variables¶

1. Go to Agent Types and select an agent type
2. Navigate to Context Settings
3. Check the variables you want to enable
4. Save changes

PATCH /api/agent-types/{id}/context-settings
{
  "enabled_builtin_variables": [
    "current_date",
    "current_year",
    "agent_name"
  ]
}

How They Appear in Context¶

Enabled variables are injected as a structured block:

## Context Variables
- current_date: December 26, 2025
- current_year: 2025
- agent_name: Support Bot

Custom Variable Sets¶

Customer-defined key-value pairs for company-specific information.

Use Cases¶

• Company contact information
• Product names and versions
• Current promotions or announcements
• Support hours and policies
• Feature flags or configuration values

Creating a Variable Set¶

Via Dashboard:

1. Go to Knowledge Base > Variable Sets
2. Click Create Variable Set
3. Enter a name and description
4. Add key-value pairs
5. Click Save

Via API:

POST /api/knowledge/variable-sets
Content-Type: application/json

{
  "name": "Support Defaults",
  "description": "Common support information",
  "variables": {
    "product_name": "AcmeWidget Pro",
    "support_email": "support@acme.com",
    "support_hours": "Monday-Friday, 9am-6pm EST",
    "refund_policy_days": "30"
  }
}

Variable Naming Rules¶

• Must start with a letter
• Can contain letters, numbers, and underscores
• Maximum 64 characters per name
• Maximum 50 variables per set
• Maximum 32KB total size per set

Attaching Variable Sets to Scopes¶

After creating a variable set, attach it to a scope:

POST /api/context/attachments
{
  "resource_type": "variable_set",
  "resource_id": 42,
  "scope_type": "team",
  "scope_id": 5,
  "priority": 0
}

How They Appear in Context¶

Custom variables are injected as a structured block:

## Custom Variables
- product_name: AcmeWidget Pro
- support_email: support@acme.com
- support_hours: Monday-Friday, 9am-6pm EST

Runtime Variables¶

Variables passed with each API request, allowing dynamic per-request context.

Passing Runtime Variables¶

Include context_variables in your API request:

POST /api/v1/agents/{id}/messages
{
  "content": "What's my order status?",
  "context_variables": {
    "user_name": "John Smith",
    "user_email": "john@example.com",
    "user_plan": "premium",
    "pending_orders": "2"
  }
}

Constraints¶

How They Appear in Context¶

Runtime variables are injected as a structured block:

## User Context (provided at request time)
- user_name: John Smith
- user_email: john@example.com
- user_plan: premium
- pending_orders: 2

Knowledge Documents¶

Upload documents to provide agents with reference material.

Supported Formats¶

Uploading Documents¶

Via Dashboard:

1. Go to Knowledge Base > Documents
2. Drag and drop files or click to browse
3. Wait for text extraction to complete
4. Attach to desired scopes

Via API:

POST /api/knowledge/documents
Content-Type: multipart/form-data

file: <binary>
name: "Product Manual"  # Optional display name

Document Processing States¶

Only documents with status: ready are included in agent context.

Attaching Documents to Scopes¶

POST /api/context/attachments
{
  "resource_type": "document",
  "resource_id": 123,
  "scope_type": "agent_type",
  "scope_id": 7,
  "priority": 10
}

Higher priority documents appear earlier in the context.

How Documents Appear in Context¶

Documents are injected with clear boundaries:

## Reference Documentation
Use the following documentation to answer questions accurately.

### Product Manual
<context_document doc_id="123" name="Product Manual">
[Full extracted text from the document...]
</context_document>

### FAQ Document
<context_document doc_id="124" name="FAQ Document">
[Full extracted text from the document...]
</context_document>

Source Citations¶

Enable source citations to have agents reference document sources:

1. Go to Agent Types > select type > Context Settings
2. Enable Include source citations
3. Save changes

With citations enabled, documents include source IDs:

### [source:1] Product Manual (doc_id=123)

And agents are instructed to cite sources inline:

"Employees receive 20 days of PTO [source:1]."

Upload Limits¶

Context Modes¶

Ag2Trust supports three modes for injecting knowledge into agent context:

Configuring Context Mode¶

Via Dashboard:

1. Go to Agent Types > select type
2. Navigate to Context Settings
3. Select the desired Context Mode
4. Save changes

Via API:

PATCH /api/agent-types/{id}
{
  "context_mode": "auto"  // or "rag" or "direct"
}

How RAG Works¶

When using rag mode (or auto mode with large document sets):

1. Documents are chunked and embedded when uploaded
2. At request time, the user's message is embedded
3. Most relevant chunks are retrieved via semantic similarity
4. Only relevant chunks are injected into context

This significantly reduces token usage for large knowledge bases while maintaining answer quality.

Choosing a Context Mode¶

Small KB (< 10K tokens total)  →  auto or direct
Large KB (> 10K tokens)        →  auto or rag
Critical reference docs        →  direct (ensures always included)
FAQ / support knowledge        →  rag (retrieves relevant answers)

Context Assembly¶

At request time, the backend assembles the effective context:

┌─────────────────────────────────────────────────────────────────────────┐
│                         REQUEST ARRIVES                                  │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  1. Load base system prompt from agent type                             │
│  2. Resolve built-in variables (if enabled)                             │
│  3. Load variable sets from org → team → agent_type scopes              │
│  4. Merge variables (later scopes override earlier)                     │
│  5. Add runtime variables (highest precedence)                          │
│  6. Load documents from all applicable scopes                           │
│  7. Assemble final context block                                        │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  FINAL PROMPT = Base System Prompt + Context Block                      │
└─────────────────────────────────────────────────────────────────────────┘

API Reference¶

Variable Sets¶

Documents¶

Context Attachments¶

Agent Type Context Settings¶

Best Practices¶

1. Use Scopes Strategically¶

Organization scope:
  └── Company-wide info (support email, company name)

Team scope:
  └── Team-specific docs (sales playbook, engineering runbooks)

Agent Type scope:
  └── Agent-specific context (specialized prompts, tools docs)

2. Keep Variables Focused¶

# Good - specific, actionable
support_email: support@acme.com
refund_policy_days: 30

# Avoid - too generic, wastes tokens
company_info: "Acme Corp was founded in 1985 and has grown..."

3. Monitor Token Usage¶

• Check token counts in the Knowledge Base dashboard
• Large documents significantly increase costs
• Consider splitting very large documents

4. Use Priority for Document Order¶

priority: 10  → Most important, appears first
priority: 0   → Default
priority: -10 → Less important, appears last

5. Test Context Assembly¶

Use the agent chat in the dashboard to verify context is being injected correctly before deploying to production.

Limits & Considerations¶

Next Steps¶

• Agents - Learn about agent configuration
• Agent Types - Configure agent templates
• Teams - Organize agents into teams
• API Reference - Complete API documentation