Azure AI Projects Py

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,
)

客户端操作概览

两种客户端方式

1. AIProjectClient（Foundry 原生）

from azure.ai.projects import AIProjectClient

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

# 使用 Foundry 原生操作
agent = client.agents.create_agent(
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    name="my-agent",
    instructions="You are helpful.",
)

2. OpenAI 兼容客户端

# 从项目获取 OpenAI 兼容客户端
openai_client = client.get_openai_client()

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

智能体操作

创建智能体（基础）

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

创建带工具的智能体

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 的版本化智能体

from azure.ai.projects.models import PromptAgentDefinition

# 创建版本化智能体
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=[],  # 按需添加工具
    ),
    version_label="v1.0",
)

详细智能体模式请参阅 references/agents.md。

工具概览

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

线程和消息流程

# 1. 创建线程
thread = client.agents.threads.create()

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

# 3. 创建并处理运行
run = client.agents.runs.create_and_process(
    thread_id=thread.id,
    agent_id=agent.id,
)

# 4. 获取响应
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)

连接

# 列出所有连接
connections = client.connections.list()
for conn in connections:
    print(f"{conn.name}: {conn.connection_type}")

# 获取特定连接
connection = client.connections.get(connection_name="my-search-connection")

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

部署

# 列出可用的模型部署
deployments = client.deployments.list()
for deployment in deployments:
    print(f"{deployment.name}: {deployment.model}")

部署模式请参阅 references/deployments.md。

数据集和索引

# 列出数据集
datasets = client.datasets.list()

# 列出索引
indexes = client.indexes.list()

数据操作请参阅 references/datasets-indexes.md。

评估

# 使用 OpenAI 客户端进行评估
openai_client = client.get_openai_client()

# 使用内置评估器创建评估
eval_run = openai_client.evals.runs.create(
    eval_id="my-eval",
    name="quality-check",
    data_source={
        "type": "custom",
        "item_references": [{"item_id": "test-1"}],
    },
    testing_criteria=[
        {"type": "fluency"},
        {"type": "task_adherence"},
    ],
)

评估模式请参阅 references/evaluation.md。

异步客户端

from azure.ai.projects.aio import AIProjectClient

async with AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
) as client:
    agent = await client.agents.create_agent(...)
    # ... 异步操作

异步模式请参阅 references/async-patterns.md。

内存存储

# 为智能体创建内存存储
memory_store = client.agents.create_memory_store(
    name="conversation-memory",
)

# 附加到智能体以实现持久化内存
agent = client.agents.create_agent(
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    name="memory-agent",
    tools=[MemorySearchTool()],
    tool_resources={"memory": {"store_ids": [memory_store.id]}},
)

最佳实践

1. 使用上下文管理器处理异步客户端：async with AIProjectClient(...) as client:
2. 完成后清理智能体：client.agents.delete_agent(agent.id)
3. 简单运行使用 create_and_process，实时 UX 使用流式传输
4. 生产部署使用版本化智能体
5. 外部服务集成优先使用连接（AI Search、Bing 等）

SDK 对比

参考文件

• references/agents.md: 使用 PromptAgentDefinition 的智能体操作
• references/tools.md: 所有智能体工具及示例
• references/evaluation.md: 评估操作概览
• references/built-in-evaluators.md: 完整内置评估器参考
• references/custom-evaluators.md: 基于代码和提示词的评估器模式
• references/connections.md: 连接操作
• references/deployments.md: 部署枚举
• references/datasets-indexes.md: 数据集和索引操作
• references/async-patterns.md: 异步客户端使用
• references/api-reference.md: 完整 API 参考（v2.0.0b4 全部 373 个 SDK 导出）
• scripts/run_batch_evaluation.py: 批量评估 CLI 工具

适用场景

本技能适用于执行概览中描述的工作流或操作。

限制

• 仅当任务明确匹配上述范围时使用本技能。
• 输出不应替代环境特定的验证、测试或专家审查。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。