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

Контекстные ответы агента

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

Подсказка

Полный рабочий пример см. в примере фоновых ответов.

Когда следует использовать фоновые ответы

Фоновые ответы особенно полезны для:

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

Как работают фоновые ответы

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

  1. Немедленное завершение: агент быстро завершает задачу и возвращает окончательный ответ без маркера продолжения.
  2. Фоновая обработка: агент начинает обработку в фоновом режиме и возвращает маркер продолжения вместо окончательного результата.

Маркер продолжения содержит все необходимые сведения для опроса завершения с помощью API агента, отличного от потоковой передачи, или возобновления прерванного потока с ПОМОЩЬЮ API агента потоковой передачи. Когда маркер nullпродолжения завершен, операция завершается. Это происходит, когда фоновый ответ завершился, завершился сбой или не может продолжить работу (например, если требуется ввод пользователя).

Включение фоновых ответов

Чтобы включить фоновые ответы, задайте для свойства AllowBackgroundResponses значение true :AgentRunOptions

AgentRunOptions options = new()
{
    AllowBackgroundResponses = true
};

Замечание

В настоящее время только агенты, использующие API ответов OpenAI, поддерживают фоновые ответы: агент ответов OpenAI и агент ответов Azure OpenAI.

Некоторые агенты могут не разрешать явный контроль над фоновыми ответами. Эти агенты могут самостоятельно решить, следует ли инициировать фоновый ответ на основе сложности операции независимо от AllowBackgroundResponses параметра.

Фоновые ответы без потоковой передачи

Для сценариев без потоковой передачи при первоначальном запуске агента он может или не возвращать маркер продолжения. Если маркер продолжения не возвращается, это означает, что операция завершена. Если маркер продолжения возвращается, он указывает, что агент инициировал фоновый ответ, который по-прежнему обрабатывается и потребует опроса для получения окончательного результата:

AIAgent agent = new AzureOpenAIClient(
    new Uri("https://<myresource>.openai.azure.com"),
    new DefaultAzureCredential())
    .GetOpenAIResponseClient("<deployment-name>")
    .AsAIAgent();

AgentRunOptions options = new()
{
    AllowBackgroundResponses = true
};

AgentSession session = await agent.CreateSessionAsync();

// Get initial response - may return with or without a continuation token
AgentResponse response = await agent.RunAsync("Write a very long novel about otters in space.", session, options);

// Continue to poll until the final response is received
while (response.ContinuationToken is not null)
{
    // Wait before polling again.
    await Task.Delay(TimeSpan.FromSeconds(2));

    options.ContinuationToken = response.ContinuationToken;
    response = await agent.RunAsync(session, options);
}

Console.WriteLine(response.Text);

Предупреждение

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

Основные моменты:

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

Потоковая передача фоновых ответов

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

AIAgent agent = new AzureOpenAIClient(
    new Uri("https://<myresource>.openai.azure.com"),
    new DefaultAzureCredential())
    .GetOpenAIResponseClient("<deployment-name>")
    .AsAIAgent();

AgentRunOptions options = new()
{
    AllowBackgroundResponses = true
};

AgentSession session = await agent.CreateSessionAsync();

AgentResponseUpdate? latestReceivedUpdate = null;

await foreach (var update in agent.RunStreamingAsync("Write a very long novel about otters in space.", session, options))
{
    Console.Write(update.Text);

    latestReceivedUpdate = update;

    // Simulate an interruption
    break;
}

// Resume from interruption point captured by the continuation token
options.ContinuationToken = latestReceivedUpdate?.ContinuationToken;
await foreach (var update in agent.RunStreamingAsync(session, options))
{
    Console.Write(update.Text);
}

Основные моменты:

  • Каждый AgentResponseUpdate содержит маркер продолжения, который можно использовать для возобновления
  • Сохранение маркера продолжения из последнего полученного обновления до прерывания
  • Использование сохраненного маркера продолжения для возобновления потока из точки прерывания

Подсказка

Полные примеры запуска см. в примерах .NET .

Подсказка

Полный рабочий пример см. в примере фоновых ответов.

Включение фоновых ответов

Чтобы включить фоновые ответы, передайте параметр при вызове backgroundagent.run():

session = agent.create_session()
response = await agent.run(
    messages="Your prompt here",
    session=session,
    options={"background": True},
)

Замечание

В настоящее время только агенты, использующие API ответов OpenAI, поддерживают фоновые ответы: агент ответов OpenAI и агент ответов Azure OpenAI.

Фоновые ответы без потоковой передачи

Для сценариев, не являющихся потоковой передачей, при первоначальном запуске агента background=Trueон может сразу же вернуться с continuation_tokenпомощью . Если continuation_token это Noneтак, операция завершена. В противном случае выполните опрос, передав маркер обратно в последующих вызовах:

import asyncio
from agent_framework import Agent
from agent_framework.openai import OpenAIResponsesClient

agent = Agent(
    name="researcher",
    instructions="You are a helpful research assistant.",
    client=OpenAIResponsesClient(model_id="o3"),
)

session = await agent.create_session()

# Start a background run — returns immediately
response = await agent.run(
    messages="Briefly explain the theory of relativity in two sentences.",
    session=session,
    options={"background": True},
)

# Poll until the operation completes
while response.continuation_token is not None:
    await asyncio.sleep(2)
    response = await agent.run(
        session=session,
        options={"continuation_token": response.continuation_token},
    )

# Done — response.text contains the final result
print(response.text)

Основные моменты

  • Начальный вызов может завершиться немедленно (без маркера продолжения) или запустить фоновую операцию (с маркером продолжения)
  • continuation_token Использование предыдущего ответа при последующих вызовах опроса
  • Когда continuation_token это Noneтак, операция завершена

Потоковая передача фоновых ответов

В сценариях потоковой передачи фоновые ответы работают как обычная потоковая передача — потоки агента обновляются в режиме реального времени. Ключевое различие заключается в том, что каждое обновление включает continuation_tokenвозобновление потоков, если подключение прервано:

session = await agent.create_session()

# Start a streaming background run
last_token = None
stream = agent.run(
    messages="Briefly list three benefits of exercise.",
    stream=True,
    session=session,
    options={"background": True},
)

# Read chunks — each update carries a continuation_token
async for update in stream:
    last_token = update.continuation_token
    if update.text:
        print(update.text, end="", flush=True)
    # If interrupted (e.g., network issue), break and resume later

Возобновление прерванного потока

Если поток прерван, используйте последний continuation_token , чтобы возобновить работу, из которого он остался:

if last_token is not None:
    stream = agent.run(
        stream=True,
        session=session,
        options={"continuation_token": last_token},
    )
    async for update in stream:
        if update.text:
            print(update.text, end="", flush=True)

Основные моменты

  • Каждая AgentResponseUpdate содержит возобновление continuation_token
  • Сохранение маркера из последнего полученного обновления до прерывания
  • Передача сохраненного маркера через options={"continuation_token": token} возобновление

Лучшие практики

При работе с фоновыми ответами рассмотрите следующие рекомендации.

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

Ограничения и рекомендации

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

Дальнейшие шаги

ТРЯПКОЙ

  • Last updated on