azure-ai-projects

Azure AI Projects client library for Python

Use the AI Projects client library (in preview) to:

• Enumerate connections in your Azure AI Foundry project and get connection properties. For example, get the inference endpoint URL and credentials associated with your Azure OpenAI connection.
• Get an authenticated Inference client to do chat completions, for the default Azure OpenAI or AI Services connections in your Azure AI Foundry project. Supports the AzureOpenAI client from the openai package, or clients from the azure-ai-inference package.
• Develop Agents using the Azure AI Agent Service, leveraging an extensive ecosystem of models, tools, and capabilities from OpenAI, Microsoft, and other LLM providers. The Azure AI Agent Service enables the building of Agents for a wide range of generative AI use cases. The package is currently in preview.
• Run Evaluations to assess the performance of generative AI applications using various evaluators and metrics. It includes built-in evaluators for quality, risk, and safety, and allows custom evaluators for specific needs.
• Enable OpenTelemetry tracing.

Product documentation | 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-projects" in the title or content.

Table of contents

• Getting started
  • Prerequisite
  • Install the package
• Key concepts
  • Create and authenticate the client
• Examples
  • Enumerate connections
    • Get properties of all connections
    • Get properties of all connections of a particular type
    • Get properties of a default connection
    • Get properties of a connection by its connection name
  • Get an authenticated ChatCompletionsClient
  • Get an authenticated AzureOpenAI client
  • Agents (Preview)
    • Create an Agent with:
      • File Search
      • Enterprise File Search
      • Code interpreter
      • Bing grounding
      • Azure AI Search
      • Function call
      • Azure Function Call
      • OpenAPI
      • Fabric data
    • 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
  • Evaluation
    • Evaluator
    • Run Evaluation in the cloud
      • Evaluators
      • Data to be evaluated
        • [Optional] Azure OpenAI Model
        • Example Remote Evaluation
  • Tracing
    • Installation
    • How to enable tracing
    • How to trace your own functions
• Troubleshooting
  • Exceptions
  • Logging
  • Reporting issues
• Next steps
• Contributing

Release History

1.0.0b10 (2025-04-23)

Features added

• Added ConnectedAgentTool class for better connected Agent support.
• Added Agent tool call tracing for all tool call types when streaming with AgentEventHandler based event handler.
• Added tracing for listing Agent run steps.
• Add a max_retry argument to the enable_auto_function_calls function to cancel the run if the maximum number of retries for auto function calls is reached.

Sample updates

• Added connected Agent tool sample.

Bugs Fixed

• Fix for filtering of messages by run ID (see GitHub issue 49513).

1.0.0b9 (2025-04-16)

Features added

• Utilities to load prompt template strings and Prompty file content
• Added BingCustomSearchTool class with sample
• Added list_threads API to agents namespace
• Added image input support for agents create_message

Sample updates

• Added project_client.agents.enable_auto_function_calls(toolset=toolset) to all samples that has toolcalls executed by azure-ai-project SDK
• New BingCustomSearchTool sample
• New samples added for image input from url, file and base64

Breaking Changes

• Redesigned automatic function calls because agents retrieved by update_agent and get_agent do not support them. With the new design, the toolset parameter in create_agent no longer executes toolcalls automatically during create_and_process_run or create_stream. To retain this behavior, call enable_auto_function_calls without additional changes.
• Because of the function calls redesign, when errors occur in FunctionTool.execute and AsyncFunctionTool.execute, they return a JSON string in the format of {error: [message]} instead of throwing errors.
• Because of the function calls redesign, when errors occur in ToolSet.execute_tool_calls and AsyncToolSet.execute_tool_calls, the returned array now includes an entry with output: {error: [message]} instead of not inserting the entry into the array.

1.0.0b8 (2025-03-28)

Features added

• New parameters added for Azure AI Search tool, with corresponding sample update.
• Fabric tool REST name updated, along with convenience code.

Sample updates

• Sample update demonstrating new parameters added for Azure AI Search tool.
• Sample added using OpenAPI tool against authenticated TripAdvisor API spec.

Bugs Fixed

• Fix for a bug in Agent tracing causing event handler return values to not be returned when tracing is enabled.
• Fix for a bug in Agent tracing causing tool calls not to be recorded in traces.
• Fix for a bug in Agent tracing causing function tool calls to not work properly when tracing is enabled.
• Fix for a bug in Agent streaming, where agent_id was not included in the response. This caused the SDK not to make function calls when the thread run status is requires_action.
• Fix for a bug in Agent create_and_process_run addresses an issue where it would get into an infinite loop when automatic function calls fail.

Features added

• Add support for parsing URL citations in Agent text messages. See new classes MessageTextUrlCitationAnnotation and MessageDeltaTextUrlCitationAnnotation.
• Add enum value ConnectionType.API_KEY to support enumeration of generic connections that uses API Key authentication.

Sample updates

• Update sample sample_agents_bing_grounding.py with printout of URL citation.
• Add new samples sample_agents_stream_eventhandler_with_bing_grounding.py and sample_agents_stream_iteration_with_bing_grounding.py with printout of URL citation.

Bugs Fixed

• Fix a bug in deserialization of RunStepDeltaFileSearchToolCall returned during Agent streaming (see GitHub issue 48333).
• Fix for Exception raised while parsing Agent streaming response, in some rare cases, for multibyte UTF-8 languages like Chinese.

Breaking Changes

• Rename input argument assistant_id to agent_id in all Agent methods to align with the "Agent" terminology. Similarly, rename all assistant_id properties on classes.

1.0.0b6 (2025-02-14)

Features added

• Added trace_function decorator for conveniently tracing function calls in Agents using OpenTelemetry. Please see the README.md for updated documentation.

Sample updates

• Added AzureLogicAppTool utility and Logic App sample under samples/agents, folder to make Azure Logic App integration with Agents easier.
• Added better observability for Azure AI Search sample for Agents via improved run steps information from the service.
• Added sample to demonstrate how to add custom attributes to telemetry span.

Bugs Fixed

• Lowered the logging level of "Toolset is not available in the client" from warning to debug to prevent unnecessary log entries in agent application runs.

1.0.0b5 (2025-01-17)

Features added

• Add method .inference.get_image_embeddings_client on AIProjectClient to get an authenticated ImageEmbeddingsClient (from the package azure-ai-inference). You need to have azure-ai-inference package version 1.0.0b7 or above installed for this method to work.

Bugs Fixed

• Fix for events dropped in streamed Agent response (see GitHub issue 39028).
• In Agents, incomplete status thread run event is now deserialized into a ThreadRun object, during stream iteration, and invokes the correct function on_thread_run (instead of the wrong function on_unhandled_event).
• Fix an error when calling the to_evaluator_model_config method of class ConnectionProperties. See new input argument include_credentials.

Breaking Changes

• submit_tool_outputs_to_run returns None instead of ThreadRun (see GitHub issue 39028).

1.0.0b4 (2024-12-20)

Bugs Fixed

• Fix for Agent streaming issue (see GitHub issue 38918)
• Fix for Agent async function send_email_async is not called (see GitHub issue 38898)
• Fix for Agent streaming with event handler fails with "AttributeError: 'MyEventHandler' object has no attribute 'buffer'" (see GitHub issue 38897)

Features Added

• Add optional input argument connection_name to methods .inference.get_chat_completions_client, .inference.get_embeddings_client and .inference.get_azure_openai_client.

1.0.0b3 (2024-12-13)

Features Added

• Add support for Structured Outputs for Agents.
• Add option to include file contents, when index search is used for Agents.
• Added objects to inform Agents about Azure Functions.
• Redesigned streaming and event handlers for agents.
• Add parallel_tool_calls parameter to allow parallel tool execution for Agents.
• Added BingGroundingTool for Agents to use against a Bing API Key connection.
• Added AzureAiSearchTool for Agents to use against an Azure AI Search resource.
• Added OpenApiTool for Agents, which creates and executes a REST function defined by an OpenAPI spec.
• Added new helper properties in OpenAIPageableListOfThreadMessage, MessageDeltaChunk, and ThreadMessage.
• Rename "AI Studio" to "AI Foundry" in package documents and samples, following recent rebranding.

Breaking Changes

• The method .agents.get_messages was removed. Please use .agents.list_messages instead.

1.0.0b2 (2024-12-03)

Bugs Fixed

• Fix a bug in the .inference operations when Entra ID authentication is used by the default connection.
• Fixed bugs occurring during streaming in function tool calls by asynchronous agents.
• Fixed bugs that were causing issues with tracing agent asynchronous functionality.
• Fix a bug causing warning about unclosed session, shown when using asynchronous credentials to create agent.
• Fix a bug that would cause agent function tool related function names and parameters to be included in traces even when content recording is not enabled.

1.0.0b1 (2024-11-15)

Features Added

First beta version