---

name: azure-ai-projects-py description: "使用azure-ai-projects SDK在Microsoft Foundry上构建AI应用程序。" risk: unknown source: community date_added: "2026-02-27"

Azure AI Projects Python SDK（Foundry SDK）

使用 azure-ai-projects SDK在Microsoft Foundry上构建AI应用程序。

安装

pip install azure-ai-projects azure-identity

环境变量

AZURE_AI_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"

认证

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

credential = DefaultAzureCredential()
client = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=credential,
)

客户端操作概览

| 操作 | 访问方式 | 用途 | |-----------|--------|---------| | client.agents | .agents.* | Agent增删改查、版本、线程、运行 | | client.connections | .connections.* | 列出/获取项目连接 | | client.deployments | .deployments.* | 列出模型部署 | | client.datasets | .datasets.* | 数据集管理 | | client.indexes | .indexes.* | 索引管理 | | client.evaluations | .evaluations.* | 运行评估 | | client.red_teams | .red_teams.* | 红队操作 |

两种客户端方式

1. AIProjectClient（原生Foundry）

from azure.ai.projects import AIProjectClient

client = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

# Use Foundry-native operations
agent = client.agents.create_agent(
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    name="my-agent",
    instructions="You are helpful.",
)

2. OpenAI兼容客户端

# Get OpenAI-compatible client from project
openai_client = client.get_openai_client()

# Use standard OpenAI API
response = openai_client.chat.completions.create(
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    messages=[{"role": "user", "content": "Hello!"}],
)

Agent操作

创建Agent（基础）

agent = client.agents.create_agent(
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    name="my-agent",
    instructions="You are a helpful assistant.",
)

创建带工具的Agent

from azure.ai.agents import CodeInterpreterTool, FileSearchTool

agent = client.agents.create_agent(
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    name="tool-agent",
    instructions="You can execute code and search files.",
    tools=[CodeInterpreterTool(), FileSearchTool()],
)

使用PromptAgentDefinition的版本化Agent

from azure.ai.projects.models import PromptAgentDefinition

# Create a versioned agent
agent_version = client.agents.create_version(
    agent_name="customer-support-agent",
    definition=PromptAgentDefinition(
        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        instructions="You are a customer support specialist.",
        tools=[],  # Add tools as needed
    ),
    version_label="v1.0",
)

详细Agent模式请参见references/agents.md。

工具概览

| 工具 | 类 | 用途 | |------|-------|----------| | Code Interpreter | CodeInterpreterTool | 执行Python、生成文件 | | File Search | FileSearchTool | 对上传文档进行RAG | | Bing Grounding | BingGroundingTool | 网络搜索（需要连接） | | Azure AI Search | AzureAISearchTool | 搜索您的索引 | | Function Calling | FunctionTool | 调用您的Python函数 | | OpenAPI | OpenApiTool | 调用REST API | | MCP | McpTool | Model Context Protocol服务器 | | Memory Search | MemorySearchTool | 搜索Agent记忆存储 | | SharePoint | SharepointGroundingTool | 搜索SharePoint内容 |

所有工具模式请参见references/tools.md。

线程和消息流程

# 1. Create thread
thread = client.agents.threads.create()

# 2. Add message
client.agents.messages.create(
    thread_id=thread.id,
    role="user",
    content="What's the weather like?",
)

# 3. Create and process run
run = client.agents.runs.create_and_process(
    thread_id=thread.id,
    agent_id=agent.id,
)

# 4. Get response
if run.status == "completed":
    messages = client.agents.messages.list(thread_id=thread.id)
    for msg in messages:
        if msg.role == "assistant":
            print(msg.content[0].text.value)

连接

# List all connections
connections = client.connections.list()
for conn in connections:
    print(f"{conn.name}: {conn.connection_type}")

# Get specific connection
connection = client.connections.get(connection_name="my-search-connection")

连接模式请参见references/connections.md。

部署

# List available model deployments
deployments = client.deployments.list()
for deployment in deployments:
    print(f"{deployment.name}: {deployment.model}")