你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用代理、对话和响应进行构建

Microsoft Foundry 代理服务使用三个核心运行时组件（agents、conversations 和 responses） 为有状态的多轮次交互提供支持。 代理使用 Foundry 模型目录中的模型以及说明和工具。 对话会在多轮中保留历史记录。 响应是代理处理输入时生成的输出。

本文逐步讲解每个组件，并演示如何在代码中将它们一起使用。 你将了解如何创建代理、启动会话、生成响应（无论是否包含代理）、添加后续消息和流式处理结果，以及Python、C#、JavaScript、Java 和 REST API 中的示例。

运行时组件如何协同工作

使用代理时，遵循一致的模式：

  • 创建代理：定义代理以开始发送消息和接收响应。
  • 创建对话（可选）：使用对话在轮次间维护历史记录。 如果不使用对话，请使用上一响应的输出来转发上下文。
  • 生成响应：代理的 Foundry 模型处理会话中的输入项以及请求中提供的任何说明。 智能体可能会将项追加到对话中。
  • 检查响应状态：监视响应，直到响应完成（尤其是在流式处理或后台模式下）。
  • 检索响应：向用户显示生成的响应。

下图演示了这些组件如何在典型的代理循环中交互。

显示代理运行时循环的关系图：代理定义和可选的聊天历史记录源响应生成，可以调用工具、将项追加回聊天中，并生成向用户显示的输出项。

你提供用户输入（以及（可选）对话历史记录），服务会生成响应（包括配置时的工具调用），并且生成的项可以重复使用为下一轮的上下文。

先决条件

若要运行本文中的示例，需要：

pip install "azure-ai-projects>=2.0.0"
pip install azure-identity

创建代理

代理是一个持久业务流程定义，它结合了 AI 模型、指令、代码、工具、参数以及可选的安全或治理控制措施。

在 Microsoft Foundry 中将代理存储为带有命名和版本的资产。 在响应生成期间，代理定义与交互历史记录（对话或以前的响应）配合使用，以处理和响应用户输入。

以下示例使用名称、模型和说明创建提示代理。 使用项目客户端进行代理创建和版本控制。

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create project client to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create a prompt agent
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant.",
    ),
)
print(f"Agent: {agent.name}, Version: {agent.version}")

注意

代理现在使用代理名称和代理版本进行标识。 他们不再有一个名为 AgentID 的 GUID。

有关其他代理类型（工作流托管），请参阅 代理开发生命周期。

使用工具创建代理

工具扩展代理除了生成文本之外可以执行的操作。 将工具附加到代理时，代理可以使用 Web 搜索或函数调用等工具调用外部服务、运行代码、搜索文件和访问数据源。

创建代理时，可以附加一个或多个工具。 在响应生成期间，代理根据用户输入及其说明决定是否调用工具。 以下示例创建附加了 Web 搜索工具的代理。

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, WebSearchTool

PROJECT_ENDPOINT = "your_project_endpoint"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create an agent with a web search tool
agent = project.agents.create_version(
    agent_name="my-tool-agent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant that can search the web.",
        tools=[WebSearchTool()],
    ),
)
print(f"Agent: {agent.name}, Version: {agent.version}")

有关可用工具的完整列表，请参阅 工具概述。 有关最佳做法，请参阅 有关使用工具的最佳做法。

生成响应

响应生成调用代理。 代理使用其配置和任何提供的历史记录（聊天或以前的响应）通过调用模型和工具来执行任务。 作为响应生成的一部分，代理会将项追加到会话中。

还可以在不定义代理的情况下生成响应。 在这种情况下，可以直接在请求中提供所有配置，并仅将其用于该响应。 此方法适用于使用最少工具的简单方案。

此外，你可以在第一个响应 ID 或第二个响应 ID 处分叉对话

使用代理生成响应

以下示例使用代理引用生成响应，然后使用前面的响应作为上下文发送后续问题。

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

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Generate a response using the agent
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
)
print(response.output_text)

# Ask a follow-up question using the previous response
follow_up = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    previous_response_id=response.id,
    input="What is the population of that city?",
)
print(follow_up.output_text)

当代理在响应生成过程中使用工具时，响应输出将包含工具调用项以及最终消息。 在打印文本响应之前，可以循环访问 response.output 以检查每个项和显示工具调用，例如 Web 搜索、函数调用或文件搜索。

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

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What happened in the news today?",
)

# Print each output item, including tool calls
for item in response.output:
    if item.type == "web_search_call":
        print(f"[Tool] Web search: status={item.status}")
    elif item.type == "function_call":
        print(f"[Tool] Function call: {item.name}({item.arguments})")
    elif item.type == "file_search_call":
        print(f"[Tool] File search: status={item.status}")
    elif item.type == "message":
        print(f"[Assistant] {item.content[0].text}")

在不存储的情况下生成响应

默认情况下，该服务在服务器端存储响应历史记录，以便可以引用 previous_response_id 的多轮次上下文。 如果你将store设置为false，则服务不会保留响应。 你必须通过将先前的输出项作为输入传递给下一个请求来自己维护对话上下文。

当你需要完全控制聊天状态、希望最小化存储的数据或在零数据保留环境中工作时，此方法非常有用。

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

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Generate a response without storing
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
    store=False,
)
print(response.output_text)

# Carry forward context client-side by passing previous output as input
follow_up = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input=[
        {"role": "user", "content": "What is the largest city in France?"},
        {"role": "assistant", "content": response.output_text},
        {"role": "user", "content": "What is the population of that city?"},
    ],
    store=False,
)
print(follow_up.output_text)

对话和对话项

对话是具有唯一标识符的持久对象。 创建后，可以在会话之间重复使用它们。

对话存储项目，其中包括消息、工具调用、工具输出和其他数据。

创建对话

以下示例创建一个包含初始用户消息的对话。 使用 OpenAI 客户端（从项目客户端获取）进行对话和响应。

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

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create a conversation with an initial user message
conversation = openai.conversations.create(
    items=[
        {
            "type": "message",
            "role": "user",
            "content": "What is the largest city in France?",
        }
    ],
)
print(f"Conversation ID: {conversation.id}")

何时使用会话

在需要时使用对话：

  • 多轮次连续性：在不自行重新生成上下文的情况下，跨轮次保持稳定的历史记录。
  • 跨会话连续性：对稍后返回的用户重复使用同一会话。
  • 更易于调试：检查一段时间内发生的情况（例如工具调用和输出）。

当会话用于生成响应（包含或不包含代理）时，完整对话将作为模型的输入提供。 然后，生成的响应将追加到同一对话。

注意

如果会话超过模型支持的上下文大小，模型将自动截断输入上下文。 对话本身不会被截断，但只使用其中一部分来生成响应。

如果未创建对话，仍可使用上一响应的输出作为下一个请求的起点生成多轮次流。 此方法比基于线程的旧模式更灵活，其中状态与线程对象紧密耦合。 有关迁移指南，请参阅 “迁移到代理 SDK”。

对话项类型

对话存储 项目 ，而不是仅存储聊天消息。 项目记录响应生成期间发生的情况，以便下一轮可以复用该上下文信息。

常见项类型包括：

  • 消息项：用户或助理消息。
  • 工具调用项：代理尝试调用工具的记录。
  • 工具输出项：工具返回的输出（例如检索结果）。
  • 输出项：显示回用户的响应内容。

向对话添加项目

创建对话后，使用conversations.items.create()添加后续用户消息或其他项目。

# Add a follow-up message to an existing conversation
openai.conversations.items.create(
    conversation_id=conversation.id,
    items=[
        {
            "type": "message",
            "role": "user",
            "content": "What about Germany?",
        }
    ],
)

使用智能体的对话

将对话与智能体引用结合，以在多轮中保持历史记录。 代理处理会话中的所有项，并自动追加其输出。

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

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create a conversation for multi-turn chat
conversation = openai.conversations.create()

# First turn
response = openai.responses.create(
    conversation=conversation.id,
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
)
print(response.output_text)

# Follow-up turn in the same conversation
follow_up = openai.responses.create(
    conversation=conversation.id,
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the population of that city?",
)
print(follow_up.output_text)

有关演示如何在代码中协同对话和响应的示例，请参阅 Foundry 代理服务中的“创建和使用内存”。

流处理与背景响应

对于长期运行的操作，您可以使用 streaming 以增量方式返回结果，或者使用 background 模式以完全异步方式运行。 在这些情况下，通常会监视响应，直到响应完成，然后使用最终输出项。

流式传输响应

流式处理会在生成结果时返回部分结果。 此方法可用于实时向用户显示输出。

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

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Stream a response using the agent
stream = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="Explain how agents work in one paragraph.",
    stream=True,
)
for event in stream:
    if hasattr(event, "delta") and event.delta:
        print(event.delta, end="", flush=True)

有关响应模式以及如何使用输出的详细信息，请参阅 响应 API。

在后台模式下运行代理

后台模式以异步方式运行代理，这对于长时间运行的任务（如复杂的推理或映像生成）非常有用。 将background设置为true，然后轮询响应状态直到完成。

from time import sleep
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Start a background response using the agent
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="Write a detailed analysis of renewable energy trends.",
    background=True,
)

# Poll until the response completes
while response.status in ("queued", "in_progress"):
    sleep(2)
    response = openai.responses.retrieve(response.id)

print(response.output_text)

将内存连接到代理（预览）

内存使代理能够跨会话保留信息，以便他们可以在一段时间内个性化响应和召回用户首选项。 如果没有内存，每个会话从头开始。

Foundry 代理服务提供通过 内存存储配置的托管内存解决方案（预览版）。 内存存储定义代理应保留的信息类型。 将内存存储附加到代理，代理在响应生成期间使用存储的内存作为附加上下文。

以下示例创建一个内存存储并将其附加到代理。

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    MemoryStoreDefaultDefinition,
    MemoryStoreDefaultOptions,
)

PROJECT_ENDPOINT = "your_project_endpoint"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create a memory store
options = MemoryStoreDefaultOptions(
    chat_summary_enabled=True,
    user_profile_enabled=True,
)
definition = MemoryStoreDefaultDefinition(
    chat_model="gpt-5.2",
    embedding_model="text-embedding-3-small",
    options=options,
)
memory_store = project.beta.memory_stores.create(
    name="my_memory_store",
    definition=definition,
    description="Memory store for my agent",
)
print(f"Memory store: {memory_store.name}")

有关概念性细节，请参阅 Foundry 智能体服务中的内存。 有关完整实现指南，请参阅 “创建和使用内存”。

安全性和数据处理

由于聊天和响应可以持久保存用户提供的内容和工具输出，因此处理运行时数据，如应用程序数据：

  • 避免在提示或聊天历史记录中存储机密。 改用连接和托管的密钥存储库（例如，设置密钥保管库连接）。
  • 使用最低权限进行工具访问。 当工具访问外部系统时，代理可能会通过该工具读取或发送数据。
  • 请谨慎处理非微软服务。 如果代理调用由非Microsoft 服务支持的工具，则某些数据可能会流向这些服务。 有关相关注意事项，请参阅了解 Foundry Tools 中的工具。

限制和约束

限制可能取决于你附加的模型、区域和工具（例如流式处理可用性和工具支持）。 有关响应的当前可用性和约束，请参阅 响应 API。

相关内容

  • Last updated on