<!-- PIPY LONG DESCRIPTION BEGIN -->

Azure AI Agents client library for Python

Use the AI Agents client library to:

• Develop Agents using the Azure AI Agents Service, leveraging an extensive ecosystem of models, tools, and capabilities from OpenAI, Microsoft, and other LLM providers. The Azure AI Agents Service enables the building of Agents for a wide range of generative AI use cases.
• Note: While this package can be used independently, we recommend using the Azure AI Projects client library (azure-ai-projects) for an enhanced experience. The Projects library provides simplified access to advanced functionality, such as creating and managing agents, enumerating AI models, working with datasets and managing search indexes, evaluating generative AI performance, and enabling OpenTelemetry tracing.

Product documentation | [Samples][samples] | API reference documentation | Package (PyPI) | SDK source code | AI Starter Template

Reporting issues

To report an issue with the client library, or request additional features, please open a GitHub issue here. Mention the package name "azure-ai-agents" in the title or content.

Table of contents

• Getting started
  • Prerequisite
  • Install the package
• Key concepts
  • Create and authenticate the client
• Examples
  • Create an Agent with:
    • File Search
    • Enterprise File Search
    • Code interpreter
    • Bing grounding
    • Azure AI Search
    • Function call
    • Azure Function Call
    • OpenAPI
  • Create thread with
    • Tool resource
  • Create message with:
    • File search attachment
    • Code interpreter attachment
    • Create Message with Image Inputs
  • Execute Run, Run_and_Process, or Stream
  • Retrieve message
  • Retrieve file
  • Tear down by deleting resource
  • Tracing
    • Installation
    • How to enable tracing
    • How to trace your own functions
• Troubleshooting
  • Logging
  • Reporting issues
• Next steps
• Contributing

<!-- PIPY LONG DESCRIPTION END -->

Getting started

Prerequisite

• Python 3.9 or later.
• An [Azure subscription][azure_sub].
• A project in Azure AI Foundry.
• The project endpoint string. It can be found in your Azure AI Foundry project overview page, under "Project details". Below we will assume the environment variable PROJECT_ENDPOINT_STRING was defined to hold this value.
• Entra ID is needed to authenticate the client. Your application needs an object that implements the TokenCredential interface. Code samples here use DefaultAzureCredential. To get that working, you will need:
  • An appropriate role assignment. see Role-based access control in Azure AI Foundry portal. Role assigned can be done via the "Access Control (IAM)" tab of your Azure AI Project resource in the Azure portal.
  • Azure CLI installed.
  • You are logged into your Azure account by running az login.
  • Note that if you have multiple Azure subscriptions, the subscription that contains your Azure AI Project resource must be your default subscription. Run az account list --output table to list all your subscription and see which one is the default. Run az account set --subscription "Your Subscription ID or Name" to change your default subscription.

Install the package

pip install azure-ai-agents

Key concepts

Create and authenticate the client

To construct a synchronous client:

import os
from azure.ai.agents import AgentsClient
from azure.identity import DefaultAzureCredential

agents_client = AgentsClient(
    endpoint=os.environ["PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

To construct an asynchronous client, Install the additional package aiohttp:

pip install aiohttp

and update the code above to import asyncio, and import AgentsClient from the azure.ai.agents.aio namespace:

import os
import asyncio
from azure.ai.agents.aio import AgentsClient
from azure.core.credentials import AzureKeyCredential

agent_client = AgentsClient(
   endpoint=os.environ["PROJECT_ENDPOINT"],
   credential=DefaultAzureCredential(),
)

Examples

Create Agent

Before creating an Agent, you need to set up Azure resources to deploy your model. Create a New Agent Quickstart details selecting and deploying your Agent Setup.

Here is an example of how to create an Agent:

<!-- SNIPPET:sample_agents_basics.create_agent -->

    agent = agents_client.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="my-agent",
        instructions="You are helpful agent",
    )

<!-- END SNIPPET -->

To allow Agents to access your resources or custom functions, you need tools. You can pass tools to create_agent by either toolset or combination of tools and tool_resources.

Here is an example of toolset:

<!-- SNIPPET:sample_agents_run_with_toolset.create_agent_toolset -->

functions = FunctionTool(user_functions)
code_interpreter = CodeInterpreterTool()

toolset = ToolSet()
toolset.add(functions)
toolset.add(code_interpreter)

# To enable tool calls executed automatically
agents_client.enable_auto_function_calls(toolset)

agent = agents_client.create_agent(
    model=os.environ["MODEL_DEPLOYMENT_NAME"],
    name="my-agent",
    instructions="You are a helpful agent",
    toolset=toolset,
)

<!-- END SNIPPET -->

Also notices that if you use asynchronous client, you use AsyncToolSet instead. Additional information related to AsyncFunctionTool be discussed in the later sections.

Here is an example to use tools and tool_resources:

<!-- SNIPPET:sample_agents_vector_store_batch_file_search.create_agent_with_tools_and_tool_resources -->

file_search_tool = FileSearchTool(vector_store_ids=[vector_store.id])

# Notices that FileSearchTool as tool and tool_resources must be added or the agent unable to search the file
agent = agents_client.create_agent(
    model=os.environ["MODEL_DEPLOYMENT_NAME"],
    name="my-agent",
    instructions="You are helpful agent",
    tools=file_search_tool.definitions,
    tool_resources=file_search_tool.resources,
)

<!-- END SNIPPET -->

In the following sections, we show you sample code in either toolset or combination of tools and tool_resources.

Create Agent with File Search

To perform file search by an Agent, we first need to upload a file, create a vector store, and associate the file to the vector store. Here is an example:

<!-- SNIPPET:sample_agents_file_search.upload_file_create_vector_store_and_agent_with_file_search_tool -->

file = agents_client.files.upload_and_poll(file_path=asset_file_path, purpose=FilePurpose.AGENTS)
print(f"Uploaded file, file ID: {file.id}")

vector_store = agents_client.vector_stores.create_and_poll(file_ids=[file.id], name="my_vectorstore")
print(f"Created vector store, vector store ID: {vector_store.id}")

# Create file search tool with resources followed by creating agent
file_search = FileSearchTool(vector_store_ids=[vector_store.id])

agent = agents_client.create_agent(
    model=os.environ["MODEL_DEPLOYMENT_NAME"],
    name="my-agent",
    instructions="Hello, you are helpful agent and can search information from uploaded files",
    tools=file_search.definitions,
    tool_resources=file_search.resources,
)

<!-- END SNIPPET -->

Create Agent with Enterprise File Search

We can upload file to Azure as it is shown in the example, or use the existing Azure blob storage. In the code below we demonstrate how this can be achieved. First we upload file to azure and create VectorStoreDataSource, which then is used to create vector store. This vector store is then given to the FileSearchTool constructor.

<!-- SNIPPET:sample_agents_enterprise_file_search.upload_file_and_create_agent_with_file_search -->

# We will upload the local file to Azure and will use it for vector store creation.
asset_uri = os.environ["AZURE_BLOB_URI"]

# Create a vector store with no file and wait for it to be processed
ds = VectorStoreDataSource(asset_identifier=asset_uri, asset_type=VectorStoreDataSourceAssetType.URI_ASSET)
vector_store = agents_client.vector_stores.create_and_poll(data_sources=[ds], name