Поделиться через

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

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

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

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

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

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

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

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

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

Предпосылки

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

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

Для получения концептуальных деталей см. "Memory in Foundry Agent Service". Полные рекомендации по реализации см. в разделе "Создание и использование памяти".

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

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

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

Предельные значения и ограничения

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

Связанный контент

  • Last updated on