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. Connect to Service
   Enter the endpoint URL and admin API key

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

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

4. Complete Strategy Settings
   Choose OpenAI and field mappings when the selected strategy needs them

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

6. Select Agent Access
   Choose which existing agents receive the new tool immediately

7. Create
   Create the source and tool, then apply the selected assignments

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. You can add a Knowledge AI Provider directly from the wizard, or manage existing resources under Capabilities > Knowledge > Knowledge Providers

Setting Up an External Knowledge Source

Navigate to Capabilities > Knowledge > Indexes and click Add External Source to launch the Azure AI Search setup wizard.

Step 1: Connection Details

Enter the Azure AI Search endpoint URL and admin API key, then click Test Connection. The wizard validates the credentials and reports the indexes available on the service. Expand the help section for Azure portal instructions.

Step 2: Select Index

Choose an index from the discovered list. Selecting an index loads its schema, document count, semantic configurations, and any linked Knowledge Base resources.

Step 3: Query Strategy

Choose how agents retrieve and present results:

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

The wizard recommends Knowledge Base when it detects one. See Query Strategies for a detailed comparison.

Step 4: OpenAI Configuration

This step appears for Knowledge Base and Search with Synthesis. Select a configured Azure OpenAI provider, or use the Knowledge Base default model when that option is available.

If no Azure OpenAI provider exists, select Configure Azure OpenAI provider. Enter and validate the Azure resource details in the dialog, then create the provider. The wizard keeps your connection, index, and strategy selections, returns you to this step, and automatically selects the new provider. If your role cannot configure Knowledge AI Providers, ask an administrator to add one and then select Check again.

Step 5: Field Mappings

This step appears for Direct Search and Search with Synthesis. Confirm the detected key, content, title, and optional semantic configuration fields. Mapped fields must be marked retrievable in Azure AI Search. The wizard excludes unavailable fields and explains how to repair the index when no usable content field remains.

Step 6: Tool Configuration

Enter a snake_case tool name, display name, user-facing description, and an LLM description that tells agents when to use the source. Specific names such as search_hr_policies are easier for agents to understand than generic names.

Step 7: Test Query

Optionally run a representative query and review the returned content, references, relevance, and synthesized answer. If results are unexpected, go back and adjust the field mappings or query strategy.

Step 8: Agent Access

Select the existing AICOS, SMEs, personal assistants, and standard agents that should receive the new tool immediately. The selection is optional and remains intact if you go Back to Test and then Continue again.

If your role cannot view or assign agents, the wizard explains the limitation and still allows you to create an unassigned source. Access can be managed later from agent settings.

Step 9: Review and Create

Review the source, index, strategy, tool configuration, and number of selected agents. Click Create Source. Outermind creates the source and tool first, then grants the returned tool to the selected agents.

If source creation succeeds but an assignment does not, the wizard keeps the created source and offers Retry Agent Access or Finish and Manage Later. Retrying does not create a duplicate source.

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 Capabilities > 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 Workforce > Agents > Agents & SMEs
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

A Field Is Excluded from Field Mappings

1. Open the index definition in Azure AI Search
2. Confirm the intended content, title, or key field is marked Retrievable
3. Save the index definition, then rediscover the index in the Outermind wizard

Azure AI Search cannot return a non-retrievable field in a query $select, so the wizard blocks that mapping before Test or Create.

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