External Knowledge Sources

External Knowledge Sources let you connect pre-existing Azure AI Search indexes to Outermind as read-only knowledge tools for AI agents. Unlike Grounded Knowledge Indexes (GKIs) where Outermind provisions, populates, and manages the full index lifecycle, External Knowledge Sources point to indexes your organization already owns and maintains. Agents query them through the same tool interface as any other knowledge tool, giving instant access to your pre-built knowledge bases without re-indexing.

Overview

External Knowledge Sources provide:

• Bring Your Own Index - Connect pre-existing Azure AI Search indexes without re-indexing or migrating data
• Three query strategies - Choose Knowledge Base, Direct Search, or Search with Synthesis depending on your index capabilities
• Auto-discovery - The setup wizard detects available indexes, fields, semantic configurations, and Knowledge Base resources automatically
• Custom tool names - Assign meaningful names like search_hr_policies so agents understand what each tool does
• Per-agent assignment - Control which agents can access which external indexes
• Extensible architecture - Built with a provider abstraction to support future backends like Pinecone and Elasticsearch

How It Works

1. Select Provider
   Choose the search platform (Azure AI Search)

2. Connect to Service
   Enter the endpoint URL and admin API key

3. Discover Indexes
   System lists all available indexes on the service

4. Configure Fields
   System auto-detects key, content, and title fields from the index schema

5. Choose Query Strategy
   Select how agents should retrieve and present results

6. Name and Test
   Assign a tool name, description, and run a test query to verify

7. Assign to Agents
   The new tool appears in the agent configuration for per-agent assignment

Prerequisites

Before configuring External Knowledge Sources, ensure you have:

1. Azure AI Search service - An existing Azure AI Search service with at least one populated index
2. Admin API key - The admin API key for the search service (found in the Azure portal under Keys)
3. Index knowledge - An understanding of which indexes contain relevant data for your agents
4. Azure OpenAI provider (optional) - Required only if you want to use the Search with Synthesis query strategy. Configure this under Build > AI Config > LLM Providers

Setting Up an External Knowledge Source

Navigate to Build > Knowledge > Knowledge Sources and click Add Source to launch the setup wizard.

Step 1: Select Provider Type

Choose the search platform that hosts your index. Currently supported:

Provider	Description
Azure AI Search	Microsoft's cloud search service with support for keyword, semantic, and vector search

Additional providers (Pinecone, Elasticsearch) will be available in future releases.

Step 2: Connection Details

Enter the credentials to connect to your search service:

Setting	Description
Endpoint URL	The full URL of your Azure AI Search service (e.g., https://my-search.search.windows.net)
Admin API Key	The admin API key from the Azure portal. Used for both index discovery and runtime queries

Click Test Connection to validate the credentials. The system will connect to your service and report the number of available indexes.

The help section on this step provides guidance on where to find these values in the Azure portal.

Step 3: Select Index

The wizard displays all indexes discovered on the search service. For each index, you can see:

Column	Description
Index Name	The name of the index as defined in Azure AI Search
Document Count	Number of documents in the index
Field Count	Number of fields in the index schema

Select the index you want to connect as a knowledge source.

Step 4: Field Mappings

The wizard introspects the selected index schema and auto-detects likely field mappings:

Field	Description
Key Field	The unique document identifier field (auto-detected)
Content Field	The primary text field containing document content
Title Field	The document title or name field
Additional Fields	Other fields to include in search results (e.g., category, author, lastModified)

Auto-detected values are shown in dropdowns. Review and override any fields if the auto-detection does not match your index structure. This step is skipped for the Knowledge Base strategy since the Knowledge Base handles field selection internally.

Step 5: Query Strategy

Choose how agents retrieve and present results from this index. The available strategies depend on what the wizard discovers on your search service:

Strategy	Description	Availability
Knowledge Base	Uses an existing Azure AI Search Knowledge Base for retrieval and answer synthesis	Only available when a Knowledge Base is detected on the index
Direct Search	Returns raw ranked search results directly to the agent	Always available for any index
Search with Synthesis	Searches the index then uses Azure OpenAI to generate a synthesized answer	Available when an Azure OpenAI provider is configured

If the wizard detects a Knowledge Base on the selected index, it will recommend the Knowledge Base strategy. See the Query Strategies section below for a detailed comparison.

Step 6: OpenAI Configuration

This step appears only when you select the Search with Synthesis strategy (or Knowledge Base if the KB's linked model is not accessible). Configure the Azure OpenAI connection used for answer generation:

Setting	Description
Azure OpenAI Provider	Select from your tenant's configured Azure OpenAI providers

If you have not configured an Azure OpenAI provider yet, go to Build > AI Config > LLM Providers to add one first.

Step 7: Tool Configuration

Define how this knowledge source appears as a tool for agents:

Setting	Description
Tool Name	A snake_case identifier used by agents (e.g., search_hr_policies, query_product_docs)
Display Name	A human-readable name shown in the admin console
Tool Description	A description that tells agents when and how to use this tool. Be specific about what data is available

Choose a descriptive tool name that helps agents understand the tool's purpose. Names like search_hr_policies are more useful than generic names like external_search_1.

Step 8: Test Query

Validate your configuration by running a sample query:

1. Enter a test query relevant to the content in the index
2. Click Run Test to execute the query
3. Review the results to verify:
   • Results are returned from the expected index
   • Content fields contain meaningful data
   • Answer synthesis (if applicable) produces coherent responses
   • Relevance scores indicate good matches

If results are unexpected, go back and adjust field mappings or strategy selection.

Step 9: Review and Create

Review the complete configuration summary:

• Provider type and endpoint
• Selected index and field mappings
• Query strategy
• Tool name and description
• Test query results

Click Create Source to save the configuration. The system creates the knowledge source record and registers it as an available agent tool.

Query Strategies

Comparison

	Knowledge Base	Direct Search	Search with Synthesis
How it works	Uses Azure AI Search agentic retrieval API with existing KB	Standard search API with semantic ranking	Standard search + Azure OpenAI answer generation
Returns	Synthesized answer + source references	Raw ranked document results	Synthesized answer + source references
Requires	Knowledge Base configured on the search service	Any Azure AI Search index	Any index + Azure OpenAI provider
Field mapping	Not needed (KB handles internally)	Required	Required
Cost	Included in Azure Search tier (if KB model is pre-configured)	Lowest cost - no additional AI calls	Additional Azure OpenAI token cost per query
Latency	Moderate (server-side synthesis)	Lowest latency	Higher latency (search + synthesis)
Best for	Indexes with existing Knowledge Base setup	Simple lookups, cost-sensitive use cases	High-quality answers when no KB exists

When to Use Each Strategy

Knowledge Base - Choose this when your Azure AI Search service already has a Knowledge Base configured for the index. This is the most turnkey option since the KB handles search, reranking, and answer synthesis server-side.

Direct Search - Choose this when you want the lowest cost and latency, or when your agents are capable of interpreting raw search results. This works well for structured data lookups where agents need specific field values rather than synthesized answers.

Search with Synthesis - Choose this when you want the quality of synthesized answers but don't have a Knowledge Base set up. This strategy combines standard search with your Azure OpenAI provider to generate coherent answers from search results.

Managing External Knowledge Sources

Viewing Sources

From Build > Knowledge > Knowledge Sources, you can see all configured sources with:

Column	Description
Name	Display name of the knowledge source
Provider	The search platform (e.g., Azure AI Search)
Strategy	The query strategy in use
Status	Current status (active, error, disabled)
Total Queries	Number of queries executed against this source
Last Query	When the source was last queried

Editing a Source

Click on a source to open its detail page. You can edit:

• Display name and description
• Tool description (how agents understand the tool)
• Query strategy (may require reconfiguration of field mappings or OpenAI provider)

Connection details (endpoint and API key) cannot be changed after creation. To connect to a different service or index, create a new source.

Disabling a Source

To temporarily stop agents from using a source without deleting it:

1. Open the source detail page
2. Click Disable
3. The tool is removed from agent tool lists until re-enabled

Deleting a Source

To permanently remove a source:

1. Open the source detail page
2. Click Delete
3. Confirm the deletion

Deleting a source removes the associated tool registration and any agent assignments. The underlying Azure AI Search index is not affected.

Testing Queries

From the source detail page, use the Test Query tab to run queries at any time. This is useful for:

• Verifying the index is still accessible
• Testing query quality after index updates
• Debugging agent behavior by reproducing their queries

Agent Integration

Assigning the Tool to Agents

Once created, the external knowledge source appears as a tool that can be assigned to agents:

1. Go to Build > AI Config > Agents
2. Select an agent to configure
3. In the Tools section, find the external knowledge source tool by its display name
4. Enable the tool for the agent

How Agents Use the Tool

During execution, when an agent determines it needs information from the external knowledge source:

1. Agent calls the tool with a search query (e.g., search_hr_policies({ query: "parental leave policy" }))
2. The query engine routes to the appropriate strategy based on the source configuration
3. Results are returned to the agent with:
   • Answer - A synthesized response (for Knowledge Base and Search with Synthesis strategies) or null (for Direct Search)
   • References - Ranked document results with titles, content snippets, and relevance scores
   • Result count - Number of matching documents found
4. The agent incorporates the information into its response, citing sources as appropriate

No additional agent configuration is needed beyond tool assignment. The tool name and description provide agents with sufficient context to know when to use the tool.

Security

External Knowledge Sources are designed with security as a core principle:

Aspect	Implementation
API Key Encryption	Admin API keys are encrypted at rest using the same encryption pattern as other platform credentials
Read-Only Access	All operations are strictly read-only. No write operations (indexing, deleting) are exposed
Tenant Isolation	Sources are scoped to the tenant that created them. Agents cannot access other tenants' sources
No Credential Exposure	API keys are never returned to the frontend after initial save. Only the endpoint URL and index name are visible
Per-Agent Control	Tool assignment via the AgentTools system ensures only authorized agents can query each source
Tool Name Uniqueness	Tool names are validated for uniqueness within the tenant to prevent conflicts

Best Practices

Start Focused

1. Begin with 1-2 high-value indexes that agents need most frequently
2. Choose indexes with clean, well-structured content
3. Test thoroughly with representative queries before deploying to production agents
4. Expand to additional indexes as you confirm value

Use Meaningful Tool Names

1. Choose descriptive snake_case names like search_hr_policies or query_product_catalog
2. Write clear tool descriptions that explain what data is available and when to use the tool
3. Avoid generic names like external_search or knowledge_1 that don't help agents make tool selection decisions

Choose the Right Strategy

1. Use Knowledge Base when available - it provides the best out-of-the-box experience
2. Use Direct Search for cost-sensitive scenarios or when agents can interpret raw results
3. Use Search with Synthesis when you need high-quality answers but don't have a Knowledge Base
4. Run test queries with each available strategy to compare result quality before committing

Optimize for Agent Success

1. Ensure your indexes have semantic configurations enabled for better search relevance
2. Keep content fields populated with meaningful text (not just metadata)
3. Use the title field to give agents useful document identifiers for citation
4. Monitor query statistics to identify low-performing sources

Troubleshooting

Connection Failures

If the Test Connection step fails:

1. Verify the endpoint URL is correct and includes the protocol (https://)
2. Confirm the admin API key is valid and has not been rotated
3. Check that the Azure AI Search service is running and accessible
4. Ensure there are no network restrictions (firewall rules, private endpoints) blocking access from Outermind

No Results Returned

If queries return no results:

1. Verify the index contains documents (check document count on the index selection step)
2. Try broader search terms that match known content in the index
3. Check that the content field mapping points to a field with searchable text
4. For semantic search, ensure the index has a semantic configuration enabled
5. Run the same query directly in the Azure portal to compare results

Poor Result Quality

If results are returned but not relevant:

1. Review field mappings - ensure the content field contains the primary searchable text
2. Consider switching strategies (e.g., from Direct Search to Search with Synthesis)
3. Verify the index has a semantic configuration for better ranking
4. Check that the tool description accurately describes the available content so agents form better queries

Query Errors at Runtime

If agents report errors when using the tool:

1. Open the source detail page and run a test query to verify connectivity
2. Check if the API key has been rotated on the Azure side
3. Verify the index still exists and has not been renamed or deleted
4. Review agent execution logs for specific error messages

Knowledge Base Strategy Not Available

If the Knowledge Base option does not appear during setup:

1. Verify the index has a Knowledge Base configured in Azure AI Search
2. Ensure you are using an admin API key (query keys cannot discover Knowledge Base resources)
3. Check that the Knowledge Base is in an active state in the Azure portal

Related Topics

• Grounded Knowledge Indexes
• Azure AI Search Setup
• Corporate Knowledge Setup
• SharePoint Knowledge Sources
• Google Drive Knowledge Sources