Сборка с помощью агентов, бесед и ответов

Служба агента Microsoft Foundry использует три основных компонента среды выполнения: агенты, разговоры и ответы — для обеспечения управления состоянием и многошаговых взаимодействий. Агент использует модель из каталога моделей Foundry, а также инструкции и средства. Беседа сохраняет историю на разных этапах. Ответ — это выходные данные, которые агент создает при обработке входных данных.

В этой статье рассматриваются все компоненты и показано, как использовать их вместе в коде. Вы узнаете, как создать агент, начать беседу, создать ответы (с агентом или без нее), добавить последующие сообщения и потоковые результаты с примерами в Python, C#, JavaScript, Java и REST API.

Совместная работа компонентов среды выполнения

При работе с агентом следует следовать согласованному шаблону:

  • Создайте агент: определите агент для начала отправки сообщений и получения ответов.
  • Создайте беседу (необязательно): используйте беседу для ведения журнала в течение различных этапов. Если вы не используете беседу, сохраните контекст, используя выходные данные из предыдущего ответа.
  • Создайте ответ: модель Foundry, используемая агентом, обрабатывает входные элементы в беседе и все инструкции, предоставленные в запросе. Агент может добавлять элементы в беседу.
  • Проверьте состояние ответа: отслеживайте ответ, пока он не завершится (особенно в режиме потоковой передачи или фонового режима).
  • Получение ответа: отображение созданного ответа пользователю.

На следующей схеме показано, как эти компоненты взаимодействуют в типичном цикле агента.

Схема, на которой показан цикл выполнения агента: определение агента и (необязательная) история разговора для генерации ответа, которая может вызывать инструменты, добавлять элементы обратно в беседу и создавать выходные элементы, отображаемые пользователю.

Вы предоставляете входные данные пользователя (и при необходимости журнал бесед), служба создает ответ (включая вызовы инструментов при настройке), а результирующий элемент можно повторно использовать в качестве контекста для следующего шага.

Необходимые условия

Чтобы выполнить примеры в этой статье, вам потребуется:

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

Создание агента

Агент — это сохранённое определение оркестрации, которое объединяет модели ИИ, инструкции, код, инструменты, параметры, а также необязательные элементы контроля безопасности или управления.

Храните агентов как именованные и версионные ресурсы в 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}")

Примечание

Теперь агенты определяются с помощью имени агента и версии агента. У них больше нет GUID, называемого AgentID.

Дополнительные типы агентов (рабочий процесс, размещение) см. в разделе жизненного цикла разработки агента.

Создание агента с помощью инструментов

Средства расширяют возможности агента за пределами создания текста. При присоединении средств к агенту агент может вызывать внешние службы, выполнять код, файлы поиска и получать доступ к источникам данных во время создания ответов с помощью таких средств, как веб-поиск или вызов функций.

При создании агента можно подключить один или несколько инструментов. Во время создания ответа агент решает, следует ли вызывать средство на основе входных данных пользователя и его инструкций. В следующем примере создается агент с подключенным средством поиска в Интернете.

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}")

Полный список доступных средств см. в обзоре инструментов. Для лучших практик см. Лучшие практики по использованию инструментов.

Создание ответов

Создание ответа активирует агента. Агент использует свою конфигурацию и любой предоставленный журнал (беседу или предыдущий ответ) для выполнения задач путем вызова моделей и инструментов. В рамках создания ответов агент добавляет элементы в беседу.

Вы также можете создать ответ без определения агента. В этом случае вы предоставляете все конфигурации непосредственно в запросе и используете их только для этого ответа. Этот подход полезен для простых сценариев с минимальными инструментами.

Кроме того, можно сделать форк разговора на идентификаторе первого ответа или второго ответа.

Сформируйте ответ с участием агента

Пример создаёт ответ, используя ссылку на агента, а затем отправляет последующий вопрос, используя предыдущий ответ как контекст.

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 для проверки каждого элемента и вызовов инструментов отображения, таких как веб-поиск, вызовы функций или поиски файлов перед печатью текстового ответа.

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 ссылаться на контекст многократных обращений. Если задано значение storefalse, служба не сохраняет ответ. Вы должны поддерживать контекст разговора самостоятельно, передавая предыдущие выходные элементы в качестве входных данных в следующий запрос.

Этот подход полезен, если требуется полный контроль над состоянием беседы, требуется свести к минимуму сохраненные данные или работать в среде хранения без данных.

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". Полные рекомендации по реализации см. в разделе "Создание и использование памяти".

Безопасность и обработка данных

Так как беседы и ответы могут сохранять предоставленные пользователем содержимое и выходные данные инструментов, обрабатывают данные среды выполнения, такие как данные приложения:

  • Избегайте хранения секретов в запросах или журнале бесед. Используйте подключения и управляемые хранилища секретов (например, Настройка подключения Key Vault).
  • Используйте минимальные привилегии для доступа к средству. Когда средство обращается к внешним системам, агент может потенциально считывать или отправлять данные через это средство.
  • Будьте осторожны с не-Microsoft услугами. Если агент вызывает средства, поддерживаемые не службы Майкрософт, некоторые данные могут передаваться в эти службы. Дополнительные сведения см. в разделе «Инструменты в Foundry Tools».

Ограничения и лимиты

Ограничения могут зависеть от модели, региона и присоединенных средств (например, поддержки потоковой передачи и поддержки инструментов). Сведения о текущей доступности и ограничениях для ответов см. в разделе API ответов.

Связанное содержимое

  • Last updated on