mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Python: renamed ai search and cleanup of samples and unified import logic (#2369)
* renamed ai search and cleanup of samples and unified import logic * fixed error messages * fixed folder name * remove old samples from readme
This commit is contained in:
Eduard van Valkenburg
committed by
GitHub
Unverified
GitHub
parent
db424d56f3
commit
9f43108ef1
@@ -20,6 +20,8 @@ This folder contains examples demonstrating different ways to create and use age
|
||||
| [`azure_ai_with_file_search.py`](azure_ai_with_file_search.py) | Shows how to use the `HostedFileSearchTool` with Azure AI agents to upload files, create vector stores, and enable agents to search through uploaded documents to answer user questions. |
|
||||
| [`azure_ai_with_hosted_mcp.py`](azure_ai_with_hosted_mcp.py) | Shows how to integrate hosted Model Context Protocol (MCP) tools with Azure AI Agent. |
|
||||
| [`azure_ai_with_response_format.py`](azure_ai_with_response_format.py) | Shows how to use structured outputs (response format) with Azure AI agents using Pydantic models to enforce specific response schemas. |
|
||||
| [`azure_ai_with_search_context_agentic.py`](../../context_providers/azure_ai_search/azure_ai_with_search_context_agentic.py) | Shows how to use AzureAISearchContextProvider with agentic mode. Uses Knowledge Bases for multi-hop reasoning across documents with query planning. Recommended for most scenarios - slightly slower with more token consumption for query planning, but more accurate results. |
|
||||
| [`azure_ai_with_search_context_semantic.py`](../../context_providers/azure_ai_search/azure_ai_with_search_context_semantic.py) | Shows how to use AzureAISearchContextProvider with semantic mode. Fast hybrid search with vector + keyword search and semantic ranking for RAG. Best for simple queries where speed is critical. |
|
||||
| [`azure_ai_with_sharepoint.py`](azure_ai_with_sharepoint.py) | Shows how to use SharePoint grounding with Azure AI agents to search through SharePoint content and answer user questions with proper citations. Requires a SharePoint connection configured in your Azure AI project. |
|
||||
| [`azure_ai_with_thread.py`](azure_ai_with_thread.py) | Demonstrates thread management with Azure AI agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. |
|
||||
| [`azure_ai_with_image_generation.py`](azure_ai_with_image_generation.py) | Shows how to use the `ImageGenTool` with Azure AI agents to generate images based on text prompts. |
|
||||
|
||||
@@ -20,8 +20,6 @@ This folder contains examples demonstrating different ways to create and use age
|
||||
| [`azure_ai_with_local_mcp.py`](azure_ai_with_local_mcp.py) | Shows how to integrate Azure AI agents with local Model Context Protocol (MCP) servers for enhanced functionality and tool integration. Demonstrates both agent-level and run-level tool configuration. |
|
||||
| [`azure_ai_with_multiple_tools.py`](azure_ai_with_multiple_tools.py) | Demonstrates how to use multiple tools together with Azure AI agents, including web search, MCP servers, and function tools. Shows coordinated multi-tool interactions and approval workflows. |
|
||||
| [`azure_ai_with_openapi_tools.py`](azure_ai_with_openapi_tools.py) | Demonstrates how to use OpenAPI tools with Azure AI agents to integrate external REST APIs. Shows OpenAPI specification loading, anonymous authentication, thread context management, and coordinated multi-API conversations using weather and countries APIs. |
|
||||
| [`azure_ai_with_search_context_agentic.py`](azure_ai_with_search_context_agentic.py) | Shows how to use AzureAISearchContextProvider with agentic mode. Uses Knowledge Bases for multi-hop reasoning across documents with query planning. Recommended for most scenarios - slightly slower with more token consumption for query planning, but more accurate results. |
|
||||
| [`azure_ai_with_search_context_semantic.py`](azure_ai_with_search_context_semantic.py) | Shows how to use AzureAISearchContextProvider with semantic mode. Fast hybrid search with vector + keyword search and semantic ranking for RAG. Best for simple queries where speed is critical. |
|
||||
| [`azure_ai_with_thread.py`](azure_ai_with_thread.py) | Demonstrates thread management with Azure AI agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. |
|
||||
|
||||
## Environment Variables
|
||||
|
||||
@@ -0,0 +1,179 @@
|
||||
# Context Provider Examples
|
||||
|
||||
Context providers enable agents to maintain memory, retrieve relevant information, and enhance conversations with external context. The Agent Framework supports various context providers for different use cases, from simple in-memory storage to advanced persistent solutions with search capabilities.
|
||||
|
||||
This folder contains examples demonstrating how to use different context providers with the Agent Framework.
|
||||
|
||||
## Overview
|
||||
|
||||
Context providers implement two key methods:
|
||||
|
||||
- **`invoking`**: Called before the agent processes a request. Provides additional context, instructions, or retrieved information to enhance the agent's response.
|
||||
- **`invoked`**: Called after the agent generates a response. Allows for storing information, updating memory, or performing post-processing.
|
||||
|
||||
## Examples
|
||||
|
||||
### Simple Context Provider
|
||||
|
||||
| File | Description | Installation |
|
||||
|------|-------------|--------------|
|
||||
| [`simple_context_provider.py`](simple_context_provider.py) | Demonstrates building a custom context provider that extracts and stores user information (name and age) from conversations. Shows how to use structured output to extract data and provide dynamic instructions based on stored context. | No additional package required - uses core `agent-framework` |
|
||||
|
||||
**Install:**
|
||||
```bash
|
||||
pip install agent-framework-azure-ai
|
||||
```
|
||||
|
||||
### Azure AI Search
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| [`azure_ai_search/azure_ai_with_search_context_agentic.py`](azure_ai_search/azure_ai_with_search_context_agentic.py) | **Agentic mode** (recommended for most scenarios): Uses Knowledge Bases in Azure AI Search for query planning and multi-hop reasoning. Provides more accurate results through intelligent retrieval. Slightly slower with more token consumption. |
|
||||
| [`azure_ai_search/azure_ai_with_search_context_semantic.py`](azure_ai_search/azure_ai_with_search_context_semantic.py) | **Semantic mode** (fast queries): Fast hybrid search combining vector and keyword search with semantic ranking. Best for scenarios where speed is critical. |
|
||||
|
||||
**Install:**
|
||||
```bash
|
||||
pip install agent-framework-azure-ai-search agent-framework-azure-ai
|
||||
```
|
||||
|
||||
**Prerequisites:**
|
||||
- Azure AI Search service with a search index
|
||||
- Azure AI Foundry project with a model deployment
|
||||
- For agentic mode: Azure OpenAI resource for Knowledge Base model calls
|
||||
- Environment variables: `AZURE_SEARCH_ENDPOINT`, `AZURE_SEARCH_INDEX_NAME`, `AZURE_AI_PROJECT_ENDPOINT`
|
||||
|
||||
**Key Concepts:**
|
||||
- **Agentic mode**: Intelligent retrieval with multi-hop reasoning, better for complex queries
|
||||
- **Semantic mode**: Fast hybrid search with semantic ranking, better for simple queries and speed
|
||||
|
||||
### Mem0
|
||||
|
||||
The [mem0](mem0/) folder contains examples using Mem0, a self-improving memory layer that enables applications to have long-term memory capabilities.
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| [`mem0/mem0_basic.py`](mem0/mem0_basic.py) | Basic example storing and retrieving user preferences across different conversation threads. |
|
||||
| [`mem0/mem0_threads.py`](mem0/mem0_threads.py) | Advanced thread scoping strategies: global scope (memories shared), per-operation scope (memories isolated), and multiple agents with different memory configurations. |
|
||||
| [`mem0/mem0_oss.py`](mem0/mem0_oss.py) | Using Mem0 Open Source self-hosted version as the context provider. |
|
||||
|
||||
**Install:**
|
||||
```bash
|
||||
pip install agent-framework-mem0
|
||||
```
|
||||
|
||||
**Prerequisites:**
|
||||
- Mem0 API key from [app.mem0.ai](https://app.mem0.ai/) OR self-host [Mem0 Open Source](https://docs.mem0.ai/open-source/overview)
|
||||
- For Mem0 Platform: `MEM0_API_KEY` environment variable
|
||||
- For Mem0 OSS: `OPENAI_API_KEY` for embedding generation
|
||||
|
||||
**Key Concepts:**
|
||||
- **Global Scope**: Memories shared across all conversation threads
|
||||
- **Thread Scope**: Memories isolated per conversation thread
|
||||
- **Memory Association**: Records can be associated with `user_id`, `agent_id`, `thread_id`, or `application_id`
|
||||
|
||||
See the [mem0 README](mem0/README.md) for detailed documentation.
|
||||
|
||||
### Redis
|
||||
|
||||
The [redis](redis/) folder contains examples using Redis (RediSearch) for persistent, searchable memory with full-text and optional hybrid vector search.
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| [`redis/redis_basics.py`](redis/redis_basics.py) | Standalone provider usage and agent integration. Demonstrates writing messages, full-text/hybrid search, persisting preferences, and tool output memory. |
|
||||
| [`redis/redis_conversation.py`](redis/redis_conversation.py) | Conversational examples showing memory persistence across sessions. |
|
||||
| [`redis/redis_threads.py`](redis/redis_threads.py) | Thread scoping: global scope, per-operation scope, and multiple agents with isolated memory via different `agent_id` values. |
|
||||
|
||||
**Install:**
|
||||
```bash
|
||||
pip install agent-framework-redis
|
||||
```
|
||||
|
||||
**Prerequisites:**
|
||||
- Running Redis with RediSearch (Redis Stack or managed service)
|
||||
- **Docker**: `docker run --name redis -p 6379:6379 -d redis:8.0.3`
|
||||
- **Redis Cloud**: [redis.io/cloud](https://redis.io/cloud/)
|
||||
- **Azure Managed Redis**: [Azure quickstart](https://learn.microsoft.com/azure/redis/quickstart-create-managed-redis)
|
||||
- Optional: `OPENAI_API_KEY` for vector embeddings (hybrid search)
|
||||
|
||||
**Key Concepts:**
|
||||
- **Full-text search**: Fast keyword-based retrieval
|
||||
- **Hybrid vector search**: Optional embeddings for semantic search (`vectorizer_choice="openai"` or `"hf"`)
|
||||
- **Memory scoping**: Partition by `application_id`, `agent_id`, `user_id`, or `thread_id`
|
||||
- **Thread scoping**: `scope_to_per_operation_thread_id=True` isolates memory per operation
|
||||
|
||||
See the [redis README](redis/README.md) for detailed documentation.
|
||||
|
||||
## Choosing a Context Provider
|
||||
|
||||
| Provider | Use Case | Persistence | Search | Complexity |
|
||||
|----------|----------|-------------|--------|------------|
|
||||
| **Simple/Custom** | Learning, prototyping, simple memory needs | No (in-memory) | No | Low |
|
||||
| **Azure AI Search** | RAG, document search, enterprise knowledge bases | Yes | Hybrid + Semantic | Medium |
|
||||
| **Mem0** | Long-term user memory, preferences, personalization | Yes (cloud/self-hosted) | Semantic | Low-Medium |
|
||||
| **Redis** | Fast retrieval, session memory, full-text + vector search | Yes | Full-text + Hybrid | Medium |
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### 1. User Preference Memory
|
||||
Store and retrieve user preferences, settings, or personal information across sessions.
|
||||
- **Examples**: `simple_context_provider.py`, `mem0/mem0_basic.py`, `redis/redis_basics.py`
|
||||
|
||||
### 2. Document Retrieval (RAG)
|
||||
Retrieve relevant documents or knowledge base articles to answer questions.
|
||||
- **Examples**: `azure_ai_search/azure_ai_with_search_context_*.py`
|
||||
|
||||
### 3. Conversation History
|
||||
Maintain conversation context across multiple turns and sessions.
|
||||
- **Examples**: `redis/redis_conversation.py`, `mem0/mem0_threads.py`
|
||||
|
||||
### 4. Thread Scoping
|
||||
Isolate memory per conversation thread or share globally across threads.
|
||||
- **Examples**: `mem0/mem0_threads.py`, `redis/redis_threads.py`
|
||||
|
||||
### 5. Multi-Agent Memory
|
||||
Different agents with isolated or shared memory configurations.
|
||||
- **Examples**: `mem0/mem0_threads.py`, `redis/redis_threads.py`
|
||||
|
||||
## Building Custom Context Providers
|
||||
|
||||
To create a custom context provider, implement the `ContextProvider` protocol:
|
||||
|
||||
```python
|
||||
from agent_framework import ContextProvider, Context, ChatMessage
|
||||
from collections.abc import MutableSequence, Sequence
|
||||
from typing import Any
|
||||
|
||||
class MyContextProvider(ContextProvider):
|
||||
async def invoking(
|
||||
self,
|
||||
messages: ChatMessage | MutableSequence[ChatMessage],
|
||||
**kwargs: Any
|
||||
) -> Context:
|
||||
"""Provide context before the agent processes the request."""
|
||||
# Return additional instructions, messages, or context
|
||||
return Context(instructions="Additional instructions here")
|
||||
|
||||
async def invoked(
|
||||
self,
|
||||
request_messages: ChatMessage | Sequence[ChatMessage],
|
||||
response_messages: ChatMessage | Sequence[ChatMessage] | None = None,
|
||||
invoke_exception: Exception | None = None,
|
||||
**kwargs: Any,
|
||||
) -> None:
|
||||
"""Process the response after the agent generates it."""
|
||||
# Store information, update memory, etc.
|
||||
pass
|
||||
|
||||
def serialize(self) -> str:
|
||||
"""Serialize the provider state for persistence."""
|
||||
return "{}"
|
||||
```
|
||||
|
||||
See `simple_context_provider.py` for a complete example.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Agent Framework Documentation](https://github.com/microsoft/agent-framework)
|
||||
- [Azure AI Search Documentation](https://learn.microsoft.com/azure/search/)
|
||||
- [Mem0 Documentation](https://docs.mem0.ai/)
|
||||
- [Redis Documentation](https://redis.io/docs/)
|
||||
@@ -0,0 +1,264 @@
|
||||
# Azure AI Search Context Provider Examples
|
||||
|
||||
Azure AI Search context provider enables Retrieval Augmented Generation (RAG) with your agents by retrieving relevant documents from Azure AI Search indexes. It supports two search modes optimized for different use cases.
|
||||
|
||||
This folder contains examples demonstrating how to use the Azure AI Search context provider with the Agent Framework.
|
||||
|
||||
## Examples
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| [`azure_ai_with_search_context_agentic.py`](azure_ai_with_search_context_agentic.py) | **Agentic mode** (recommended for most scenarios): Uses Knowledge Bases in Azure AI Search for query planning and multi-hop reasoning. Provides more accurate results through intelligent retrieval with automatic query reformulation. Slightly slower with more token consumption for query planning. [Learn more](https://techcommunity.microsoft.com/blog/azure-ai-foundry-blog/foundry-iq-boost-response-relevance-by-36-with-agentic-retrieval/4470720) |
|
||||
| [`azure_ai_with_search_context_semantic.py`](azure_ai_with_search_context_semantic.py) | **Semantic mode** (fast queries): Fast hybrid search combining vector and keyword search with semantic ranking. Returns raw search results as context. Best for scenarios where speed is critical and simple retrieval is sufficient. |
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install agent-framework-azure-ai-search agent-framework-azure-ai
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Required Resources
|
||||
|
||||
1. **Azure AI Search service** with a search index containing your documents
|
||||
- [Create Azure AI Search service](https://learn.microsoft.com/azure/search/search-create-service-portal)
|
||||
- [Create and populate a search index](https://learn.microsoft.com/azure/search/search-what-is-an-index)
|
||||
|
||||
2. **Azure AI Foundry project** with a model deployment
|
||||
- [Create Azure AI Foundry project](https://learn.microsoft.com/azure/ai-studio/how-to/create-projects)
|
||||
- Deploy a model (e.g., GPT-4o)
|
||||
|
||||
3. **For Agentic mode only**: Azure OpenAI resource for Knowledge Base model calls
|
||||
- [Create Azure OpenAI resource](https://learn.microsoft.com/azure/ai-services/openai/how-to/create-resource)
|
||||
- Note: This is separate from your Azure AI Foundry project endpoint
|
||||
|
||||
### Authentication
|
||||
|
||||
Both examples support two authentication methods:
|
||||
|
||||
- **API Key**: Set `AZURE_SEARCH_API_KEY` environment variable
|
||||
- **Entra ID (Managed Identity)**: Uses `DefaultAzureCredential` when API key is not provided
|
||||
|
||||
Run `az login` if using Entra ID authentication.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
**Common (both modes):**
|
||||
- `AZURE_SEARCH_ENDPOINT`: Your Azure AI Search endpoint (e.g., `https://myservice.search.windows.net`)
|
||||
- `AZURE_SEARCH_INDEX_NAME`: Name of your search index
|
||||
- `AZURE_AI_PROJECT_ENDPOINT`: Your Azure AI Foundry project endpoint
|
||||
- `AZURE_AI_MODEL_DEPLOYMENT_NAME`: Model deployment name (e.g., `gpt-4o`, defaults to `gpt-4o`)
|
||||
- `AZURE_SEARCH_API_KEY`: _(Optional)_ Your search API key - if not provided, uses DefaultAzureCredential
|
||||
|
||||
**Agentic mode only:**
|
||||
- `AZURE_SEARCH_KNOWLEDGE_BASE_NAME`: Name of your Knowledge Base in Azure AI Search
|
||||
- `AZURE_OPENAI_RESOURCE_URL`: Your Azure OpenAI resource URL (e.g., `https://myresource.openai.azure.com`)
|
||||
- **Important**: This is different from `AZURE_AI_PROJECT_ENDPOINT` - Knowledge Base needs the OpenAI endpoint for model calls
|
||||
|
||||
### Example .env file
|
||||
|
||||
**For Semantic Mode:**
|
||||
```env
|
||||
AZURE_SEARCH_ENDPOINT=https://myservice.search.windows.net
|
||||
AZURE_SEARCH_INDEX_NAME=my-index
|
||||
AZURE_AI_PROJECT_ENDPOINT=https://myproject.api.azureml.ms
|
||||
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
|
||||
# Optional - omit to use Entra ID
|
||||
AZURE_SEARCH_API_KEY=your-search-key
|
||||
```
|
||||
|
||||
**For Agentic Mode (add these to semantic mode variables):**
|
||||
```env
|
||||
AZURE_SEARCH_KNOWLEDGE_BASE_NAME=my-knowledge-base
|
||||
AZURE_OPENAI_RESOURCE_URL=https://myresource.openai.azure.com
|
||||
```
|
||||
|
||||
## Search Modes Comparison
|
||||
|
||||
| Feature | Semantic Mode | Agentic Mode |
|
||||
|---------|--------------|--------------|
|
||||
| **Speed** | Fast | Slower (query planning overhead) |
|
||||
| **Token Usage** | Lower | Higher (query reformulation) |
|
||||
| **Retrieval Strategy** | Hybrid search + semantic ranking | Multi-hop reasoning with Knowledge Base |
|
||||
| **Query Handling** | Direct search | Automatic query reformulation |
|
||||
| **Best For** | Simple queries, speed-critical apps | Complex queries, multi-document reasoning |
|
||||
| **Additional Setup** | None | Requires Knowledge Base + OpenAI resource |
|
||||
|
||||
### When to Use Semantic Mode
|
||||
|
||||
- **Simple queries** where direct keyword/vector search is sufficient
|
||||
- **Speed is critical** and you need low latency
|
||||
- **Straightforward retrieval** from single documents
|
||||
- **Lower token costs** are important
|
||||
|
||||
### When to Use Agentic Mode
|
||||
|
||||
- **Complex queries** requiring multi-hop reasoning
|
||||
- **Cross-document analysis** where information spans multiple sources
|
||||
- **Ambiguous queries** that benefit from automatic reformulation
|
||||
- **Higher accuracy** is more important than speed
|
||||
- You need **intelligent query planning** and document synthesis
|
||||
|
||||
## How the Examples Work
|
||||
|
||||
### Semantic Mode Flow
|
||||
|
||||
1. User query is sent to Azure AI Search
|
||||
2. Hybrid search (vector + keyword) retrieves relevant documents
|
||||
3. Semantic ranking reorders results for relevance
|
||||
4. Top-k documents are returned as context
|
||||
5. Agent generates response using retrieved context
|
||||
|
||||
### Agentic Mode Flow
|
||||
|
||||
1. User query is sent to the Knowledge Base
|
||||
2. Knowledge Base plans the retrieval strategy
|
||||
3. Multiple search queries may be executed (multi-hop)
|
||||
4. Retrieved information is synthesized
|
||||
5. Enhanced context is provided to the agent
|
||||
6. Agent generates response with comprehensive context
|
||||
|
||||
## Code Example
|
||||
|
||||
### Semantic Mode
|
||||
|
||||
```python
|
||||
from agent_framework import ChatAgent
|
||||
from agent_framework.azure import AzureAIAgentClient, AzureAISearchContextProvider
|
||||
from azure.identity.aio import DefaultAzureCredential
|
||||
|
||||
# Create search provider with semantic mode (default)
|
||||
search_provider = AzureAISearchContextProvider(
|
||||
endpoint=search_endpoint,
|
||||
index_name=index_name,
|
||||
api_key=search_key, # Or use credential for Entra ID
|
||||
mode="semantic", # Default mode
|
||||
top_k=3, # Number of documents to retrieve
|
||||
)
|
||||
|
||||
# Create agent with search context
|
||||
async with AzureAIAgentClient(async_credential=DefaultAzureCredential()) as client:
|
||||
async with ChatAgent(
|
||||
chat_client=client,
|
||||
model=model_deployment,
|
||||
context_providers=search_provider,
|
||||
) as agent:
|
||||
response = await agent.run("What information is in the knowledge base?")
|
||||
```
|
||||
|
||||
### Agentic Mode
|
||||
|
||||
```python
|
||||
from agent_framework.azure import AzureAISearchContextProvider
|
||||
|
||||
# Create search provider with agentic mode
|
||||
search_provider = AzureAISearchContextProvider(
|
||||
endpoint=search_endpoint,
|
||||
index_name=index_name,
|
||||
api_key=search_key,
|
||||
mode="agentic", # Enable agentic retrieval
|
||||
knowledge_base_name=knowledge_base_name,
|
||||
azure_openai_resource_url=azure_openai_resource_url,
|
||||
top_k=5,
|
||||
)
|
||||
|
||||
# Use with agent (same as semantic mode)
|
||||
async with ChatAgent(
|
||||
chat_client=client,
|
||||
model=model_deployment,
|
||||
context_providers=search_provider,
|
||||
) as agent:
|
||||
response = await agent.run("Analyze and compare topics across documents")
|
||||
```
|
||||
|
||||
## Running the Examples
|
||||
|
||||
1. **Set up environment variables** (see Configuration section above)
|
||||
|
||||
2. **Ensure you have an Azure AI Search index** with documents:
|
||||
```bash
|
||||
# Verify your index exists
|
||||
curl -X GET "https://myservice.search.windows.net/indexes/my-index?api-version=2024-07-01" \
|
||||
-H "api-key: YOUR_API_KEY"
|
||||
```
|
||||
|
||||
3. **For agentic mode**: Create a Knowledge Base in Azure AI Search
|
||||
- [Knowledge Base documentation](https://learn.microsoft.com/azure/search/knowledge-store-create-portal)
|
||||
|
||||
4. **Run the examples**:
|
||||
```bash
|
||||
# Semantic mode (fast, simple)
|
||||
python azure_ai_with_search_context_semantic.py
|
||||
|
||||
# Agentic mode (intelligent, complex)
|
||||
python azure_ai_with_search_context_agentic.py
|
||||
```
|
||||
|
||||
## Key Parameters
|
||||
|
||||
### Common Parameters
|
||||
|
||||
- `endpoint`: Azure AI Search service endpoint
|
||||
- `index_name`: Name of the search index
|
||||
- `api_key`: API key for authentication (optional, can use credential instead)
|
||||
- `credential`: Azure credential for Entra ID auth (e.g., `DefaultAzureCredential()`)
|
||||
- `mode`: Search mode - `"semantic"` (default) or `"agentic"`
|
||||
- `top_k`: Number of documents to retrieve (default: 3 for semantic, 5 for agentic)
|
||||
|
||||
### Semantic Mode Parameters
|
||||
|
||||
- `semantic_configuration`: Name of semantic configuration in your index (optional)
|
||||
- `query_type`: Query type - `"semantic"` for semantic search (default)
|
||||
|
||||
### Agentic Mode Parameters
|
||||
|
||||
- `knowledge_base_name`: Name of your Knowledge Base (required)
|
||||
- `azure_openai_resource_url`: Azure OpenAI resource URL (required)
|
||||
- `max_search_queries`: Maximum number of search queries to generate (default: 3)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Authentication errors**
|
||||
- Ensure `AZURE_SEARCH_API_KEY` is set, or run `az login` for Entra ID auth
|
||||
- Verify your credentials have search permissions
|
||||
|
||||
2. **Index not found**
|
||||
- Verify `AZURE_SEARCH_INDEX_NAME` matches your index name exactly
|
||||
- Check that the index exists and contains documents
|
||||
|
||||
3. **Agentic mode errors**
|
||||
- Ensure `AZURE_SEARCH_KNOWLEDGE_BASE_NAME` is correctly configured
|
||||
- Verify `AZURE_OPENAI_RESOURCE_URL` points to your Azure OpenAI resource (not AI Foundry endpoint)
|
||||
- Check that your OpenAI resource has the necessary model deployments
|
||||
|
||||
4. **No results returned**
|
||||
- Verify your index has documents with vector embeddings (for semantic/hybrid search)
|
||||
- Check that your queries match the content in your index
|
||||
- Try increasing `top_k` parameter
|
||||
|
||||
5. **Slow responses in agentic mode**
|
||||
- This is expected - agentic mode trades speed for accuracy
|
||||
- Reduce `max_search_queries` if needed
|
||||
- Consider semantic mode for speed-critical applications
|
||||
|
||||
## Performance Tips
|
||||
|
||||
- **Use semantic mode** as the default for most scenarios - it's fast and effective
|
||||
- **Switch to agentic mode** when you need multi-hop reasoning or complex queries
|
||||
- **Adjust `top_k`** based on your needs - higher values provide more context but increase token usage
|
||||
- **Enable semantic configuration** in your index for better semantic ranking
|
||||
- **Use Entra ID authentication** in production for better security
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Azure AI Search Documentation](https://learn.microsoft.com/azure/search/)
|
||||
- [Azure AI Foundry Documentation](https://learn.microsoft.com/azure/ai-studio/)
|
||||
- [RAG with Azure AI Search](https://learn.microsoft.com/azure/search/retrieval-augmented-generation-overview)
|
||||
- [Semantic Search in Azure AI Search](https://learn.microsoft.com/azure/search/semantic-search-overview)
|
||||
- [Knowledge Bases in Azure AI Search](https://learn.microsoft.com/azure/search/knowledge-store-concept-intro)
|
||||
- [Agentic Retrieval Blog Post](https://techcommunity.microsoft.com/blog/azure-ai-foundry-blog/foundry-iq-boost-response-relevance-by-36-with-agentic-retrieval/4470720)
|
||||
+1
-2
@@ -4,8 +4,7 @@ import asyncio
|
||||
import os
|
||||
|
||||
from agent_framework import ChatAgent
|
||||
from agent_framework_aisearch import AzureAISearchContextProvider
|
||||
from agent_framework_azure_ai import AzureAIAgentClient
|
||||
from agent_framework.azure import AzureAIAgentClient, AzureAISearchContextProvider
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
from dotenv import load_dotenv
|
||||
|
||||
+1
-2
@@ -4,8 +4,7 @@ import asyncio
|
||||
import os
|
||||
|
||||
from agent_framework import ChatAgent
|
||||
from agent_framework_aisearch import AzureAISearchContextProvider
|
||||
from agent_framework_azure_ai import AzureAIAgentClient
|
||||
from agent_framework.azure import AzureAIAgentClient, AzureAISearchContextProvider
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
from dotenv import load_dotenv
|
||||
|
||||
@@ -5,7 +5,7 @@ from collections.abc import MutableSequence, Sequence
|
||||
from typing import Any
|
||||
|
||||
from agent_framework import ChatAgent, ChatClientProtocol, ChatMessage, ChatOptions, Context, ContextProvider
|
||||
from agent_framework.azure import AzureAIAgentClient
|
||||
from agent_framework.azure import AzureAIClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
from pydantic import BaseModel
|
||||
|
||||
@@ -47,7 +47,8 @@ class UserInfoMemory(ContextProvider):
|
||||
result = await self._chat_client.get_response(
|
||||
messages=request_messages, # type: ignore
|
||||
chat_options=ChatOptions(
|
||||
instructions="Extract the user's name and age from the message if present. If not present return nulls.",
|
||||
instructions="Extract the user's name and age from the message if present. "
|
||||
"If not present return nulls.",
|
||||
response_format=UserInfo,
|
||||
),
|
||||
)
|
||||
@@ -90,7 +91,7 @@ class UserInfoMemory(ContextProvider):
|
||||
|
||||
async def main():
|
||||
async with AzureCliCredential() as credential:
|
||||
chat_client = AzureAIAgentClient(async_credential=credential)
|
||||
chat_client = AzureAIClient(async_credential=credential)
|
||||
|
||||
# Create the memory provider
|
||||
memory_provider = UserInfoMemory(chat_client)
|
||||
|
||||
Reference in New Issue
Block a user