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 variables, values 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. Click Save

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 Variables¶

Customer-defined variables for company-specific information. Each variable is an individual record with a name, data type, and optional validation.

Use Cases¶

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

Creating Variables¶

1. Go to Knowledge Base > Variables
2. Click Create Variable
3. Configure the variable:
4. Name: UPPERCASE_SNAKE_CASE identifier (e.g., SUPPORT_EMAIL)
5. Label: Human-readable display name
6. Data type: string, int, float, boolean, or date
7. Validator: none, email, url, phone, or regex
8. Static vs Dynamic: Static variables store an encrypted value; dynamic variables are provided at runtime via context_variables
9. Click Save

Variable Properties¶

Reserved Variable Names¶

The following names are reserved for built-in variables and cannot be used:

CURRENT_DATE, CURRENT_TIME, CURRENT_DATETIME, AGENT_NAME, AGENT_TYPE, CUSTOMER_NAME, TEAM_NAME, CONVERSATION_ID, THREAD_ID, SESSION_ID, REQUEST_ID

Attaching Variables to Scopes¶

After creating variables, attach them to scopes in the dashboard:

1. Go to Knowledge Base > Context Attachments
2. Click Attach Resource
3. Select the variable and the desired scope:

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/ask/support
{
  "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¶

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

You can also upload documents programmatically via the Customer API. See the Knowledge Base API reference.

Document Processing States¶

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

Attaching Documents to Scopes¶

After uploading, attach documents to scopes in the dashboard:

1. Go to Knowledge Base > Context Attachments
2. Click Attach Resource
3. Select the document and the desired scope (Organization, Team, or Agent Type)
4. Set a priority value — 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¶

Live Context¶

Live context entries provide dynamic data that is resolved at agent assembly time. Unlike static documents or variables, live context can fetch fresh data from external sources on every request.

Use Cases¶

• Real-time inventory or pricing data
• Current user account status from your backend
• Live system health or metrics
• Dynamic configuration that changes frequently

Resolver Types¶

Creating a Live Context Entry¶

1. Go to Knowledge Base > Live Context
2. Click Add Live Context
3. Configure:
4. Slug: Unique identifier (e.g., inventory-status)
5. Display Name: Human-readable label
6. Resolver Type: builtin or custom
7. For custom resolvers: provide a webhook URL
8. Click Save

Available Builtin Resolvers¶

View available builtin resolvers in the dashboard under Knowledge Base > Live Context > Add Live Context > Resolver Type dropdown.

Configuration Options¶

How It Works¶

1. Agent receives a request
2. Backend checks for live context entries attached to the agent's scope
3. For each entry, the resolver is called (or cache is used)
4. Resolved data is injected into the agent's context alongside variables and documents

Context Modes¶

Ag2Trust supports three modes for injecting knowledge into agent context:

Configuring Context Mode¶

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

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 custom variables 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                      │
└─────────────────────────────────────────────────────────────────────────┘

Customer API Reference¶

The following endpoints are available to API key holders for managing knowledge documents programmatically. See the Knowledge Base API reference for full details.

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