/agent-framework-azure-ai-py

Hosted Tools Reference

Detailed patterns for all hosted tools available in the Agent Framework.

HostedCodeInterpreterTool

Enables agents to execute Python code on the Azure AI service.

Basic Usage

from agent_framework import HostedCodeInterpreterTool
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential

async with (
    AzureCliCredential() as credential,
    AzureAIAgentsProvider(credential=credential) as provider,
):
    agent = await provider.create_agent(
        name="CodingAgent",
        instructions="You can write and execute Python code to solve problems.",
        tools=HostedCodeInterpreterTool(),
    )
    
    result = await agent.run("Calculate the factorial of 20 using Python")
    print(result.text)

With File Inputs

from agent_framework import HostedCodeInterpreterTool, HostedFileContent

# Reference a file already uploaded to the service
code_tool = HostedCodeInterpreterTool(
    inputs=[
        HostedFileContent(file_id="file-abc123"),
    ]
)

agent = await provider.create_agent(
    name="DataAnalyst",
    instructions="Analyze the provided data file.",
    tools=code_tool,
)

Common Use Cases

• Data analysis and visualization
• Mathematical calculations
• File processing (CSV, JSON, etc.)
• Code generation and testing

HostedFileSearchTool

Enables agents to search through documents using vector stores.

Setup with Vector Store

from pathlib import Path
from agent_framework import HostedFileSearchTool, HostedVectorStoreContent
from agent_framework.azure import AzureAIAgentsProvider
from azure.ai.agents.aio import AgentsClient
from azure.identity.aio import AzureCliCredential

async with (
    AzureCliCredential() as credential,
    AgentsClient(endpoint=endpoint, credential=credential) as agents_client,
    AzureAIAgentsProvider(agents_client=agents_client) as provider,
):
    # Upload file to the service
    file = await agents_client.files.upload(
        file_path=Path("data/knowledge_base.txt"),
        purpose="agents"
    )
    
    # Create vector store from file
    vector_store = await agents_client.vector_stores.create_and_poll(
        file_ids=[file.id],
        name="my_knowledge_store"
    )
    
    # Create file search tool with vector store
    file_search_tool = HostedFileSearchTool(
        inputs=[HostedVectorStoreContent(vector_store_id=vector_store.id)],
        max_results=10,  # Optional: limit search results
    )
    
    agent = await provider.create_agent(
        name="ResearchAgent",
        instructions="Search the knowledge base to answer questions accurately.",
        tools=file_search_tool,
    )
    
    result = await agent.run("What are the key findings in the document?")
    print(result.text)

Multiple Vector Stores

file_search_tool = HostedFileSearchTool(
    inputs=[
        HostedVectorStoreContent(vector_store_id="vs-policy-docs"),
        HostedVectorStoreContent(vector_store_id="vs-technical-specs"),
    ],
    max_results=20,
)

Common Use Cases

• Document Q&A
• Knowledge base retrieval
• Policy/procedure lookup
• Technical documentation search

HostedWebSearchTool

Enables agents to search the web using Bing.

Basic Bing Grounding

import os
from agent_framework import HostedWebSearchTool
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential

# Requires BING_CONNECTION_ID environment variable
os.environ["BING_CONNECTION_ID"] = "your-bing-connection-id"

async with (
    AzureCliCredential() as credential,
    AzureAIAgentsProvider(credential=credential) as provider,
):
    agent = await provider.create_agent(
        name="SearchAgent",
        instructions="Search the web for current information to answer questions.",
        tools=HostedWebSearchTool(
            name="Bing Grounding Search",
            description="Search the web for current information",
        ),
    )
    
    result = await agent.run("What are the latest developments in AI?")
    print(result.text)

Bing Custom Search

For searching a custom index of websites:

import os

# Requires custom search configuration
os.environ["BING_CUSTOM_CONNECTION_ID"] = "your-custom-bing-connection-id"
os.environ["BING_CUSTOM_INSTANCE_NAME"] = "your-custom-instance"

bing_custom_tool = HostedWebSearchTool(
    name="Bing Custom Search",
    description="Search specific websites for relevant information",
)

Common Use Cases

• Current events and news
• Real-time information lookup
• Fact-checking
• Research assistance

HostedImageGenerationTool

Enables agents to generate images (when available on the service).

from agent_framework import HostedImageGenerationTool

agent = await provider.create_agent(
    name="CreativeAgent",
    instructions="You can generate images based on descriptions.",
    tools=HostedImageGenerationTool(),
)

Combining Multiple Tools

Agents can use multiple tools simultaneously:

from typing import Annotated
from pydantic import Field
from agent_framework import (
    HostedCodeInterpreterTool,
    HostedFileSearchTool,
    HostedWebSearchTool,
    HostedVectorStoreContent,
)

# Custom function tool
def get_current_date() -> str:
    """Get today's date."""
    from datetime import date
    return date.today().isoformat()

async with (
    AzureCliCredential() as credential,
    AgentsClient(endpoint=endpoint, credential=credential) as agents_client,
    AzureAIAgentsProvider(agents_client=agents_client) as provider,
):
    # Setup vector store first
    vector_store = await agents_client.vector_stores.create_and_poll(
        file_ids=[uploaded_file.id],
        name="docs_store"
    )
    
    agent = await provider.create_agent(
        name="SuperAgent",
        instructions="""You are a versatile assistant with multiple capabilities:
        - Execute Python code for calculations and data analysis
        - Search internal documents for company information
        - Search the web for current external information
        - Provide current date when needed
        
        Choose the appropriate tool based on the user's question.""",
        tools=[
            get_current_date,  # Function tool
            HostedCodeInterpreterTool(),
            HostedFileSearchTool(
                inputs=[HostedVectorStoreContent(vector_store_id=vector_store.id)]
            ),
            HostedWebSearchTool(name="Bing"),
        ],
    )

Tool Selection Guidelines

Error Handling

from agent_framework import AgentResponseUpdate

async for chunk in agent.run_stream("Analyze this data"):
    if isinstance(chunk, AgentResponseUpdate):
        # Check for tool execution errors
        if chunk.tool_calls:
            for tool_call in chunk.tool_calls:
                if hasattr(tool_call, 'error') and tool_call.error:
                    print(f"Tool error: {tool_call.error}")
    if chunk.text:
        print(chunk.text, end="", flush=True)