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

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

Tip

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

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

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

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

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

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

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

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

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

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

using Microsoft.Agents.AI;

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

Замечание

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

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

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

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

using System;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
    .AsAIAgent(
        model: "<deployment-name>",
        instructions: "You are a helpful assistant.");

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 потоковой передачи:

using System;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
    .AsAIAgent(
        model: "<deployment-name>",
        instructions: "You are a helpful assistant.");

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

Tip

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

Tip

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

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

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

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

Замечание

Python агенты, поддерживаемые API ответов OpenAI, API Azure OpenAI Responses или Microsoft Foundry поддерживают фоновые ответы.

При использовании FoundryChatClientфоновых ответов можно запускать локальные средства функций с хранилищем ответов на стороне поставщика (store=True) или воспроизведением без отслеживания состояния (store=False). Сохраняйте тот же сеанс во время опроса, чтобы возобновление ответа может продолжить цикл локального инструмента.

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

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

import asyncio
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

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

session = 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 = 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} возобновление

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

Передайте agent.AllowBackgroundResponses(true) при запуске выполнения и повторно используете явный сеанс.agent.WithSession(session) Поставщик и развертывание должны поддерживать фоновое выполнение; Параметр не делает каждый агент асинхронным.

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

Запустите операцию, а затем опрос в то время как response.ContinuationToken не пуст. Продолжить с a.Run(ctx, nil, ...), а не RunText: вызовы продолжения не должны содержать новые сообщения.

Поддерживаемый Azure пример ответов OpenAI ограничивает операцию временем ожидания, ожиданием между опросами и немедленно останавливается при отмене:

// Copyright (c) Microsoft. All rights reserved.

// This sample demonstrates long-running agent operations using the OpenAI
// Responses API "background" option. A background run returns quickly with a
// continuation token instead of the final answer; the caller then polls with
// that token until the operation completes.
//
// Ported from the Python getting-started "background responses" sample.
package main

import (
    "context"
    "time"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/examples/internal/demo"
    "github.com/microsoft/agent-framework-go/provider/openaiprovider"
    "github.com/openai/openai-go/v3"
    "github.com/openai/openai-go/v3/azure"
    "github.com/openai/openai-go/v3/option"
)

var logger = demo.NewLogger(
    "Background Responses",
    "Starts a background Responses run and polls with the continuation token until it completes.",
    "Model", demo.Deployment,
)

func main() {
    // Bound the whole sample so a run that never completes (stuck queued, a bad
    // continuation token, etc.) cannot hang indefinitely.
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
    defer cancel()

    token := demo.AzureTokenCredential()

    client := openai.NewClient(
        option.WithBaseURL(demo.Endpoint),
        azure.WithTokenCredential(token),
    )

    researcher := openaiprovider.NewResponsesAgent(
        client,
        openaiprovider.AgentConfig{
            Model:        demo.Deployment,
            Instructions: "You are a helpful research assistant. Be concise.",
            Config: agent.Config{
                Name:        "Researcher",
                Middlewares: []agent.Middleware{logger},
            },
        },
    )

    // Background runs are tied to a session so that follow-up polls target the
    // same operation.
    session, err := researcher.CreateSession(ctx)
    if err != nil {
        demo.Panic(err)
    }

    // Start a background run. It returns quickly with a continuation token
    // rather than the final answer. (If the model or endpoint does not support
    // background execution, the run simply completes inline with no token.)
    resp, err := researcher.RunText(ctx,
        "Briefly explain the theory of relativity in two sentences.",
        agent.WithSession(session),
        agent.AllowBackgroundResponses(true),
    ).Collect()
    if err != nil {
        demo.Panic(err)
    }

    // Poll until the operation completes — i.e. until a run no longer returns a
    // continuation token. Continuation runs must not carry any messages, so use
    // Run with a nil message slice.
    for resp.ContinuationToken != "" {
        // Wait between polls, but stop promptly if the context is cancelled or
        // its deadline is reached rather than sleeping through it.
        select {
        case <-ctx.Done():
            demo.Panic(ctx.Err())
        case <-time.After(2 * time.Second):
        }
        resp, err = researcher.Run(ctx, nil,
            agent.WithSession(session),
            agent.WithContinuationToken(resp.ContinuationToken),
        ).Collect()
        if err != nil {
            demo.Panic(err)
        }
    }

    // The final response holds the completed result.
    demo.Response(resp, nil)
}

Задайте AZURE_OPENAI_ENDPOINT и AZURE_OPENAI_DEPLOYMENT_NAMEвыполните проверку подлинности с помощью Azure учетных данных перед выполнением этого примера. Он печатает завершенный ответ после завершения опроса. Немедленно завершенный ответ не имеет маркера продолжения и не нуждается в опросе.

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

Запуск потоковой передачи с помощью agent.Stream(true) и agent.AllowBackgroundResponses(true). Сохраните маркер продолжения из последнего полученного обновления. Если подключение прервано, возобновите работу без новых сообщений:

for update, err := range a.Run(
    ctx,
    nil,
    agent.WithSession(session),
    agent.WithContinuationToken(lastToken),
    agent.Stream(true),
) {
    if err != nil {
        panic(err)
    }
    lastToken = update.ContinuationToken
    fmt.Print(update.String())
}

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

Использование фоновых ответов с агентом Use

Агент Use остается стандартным агентом Agent Framework, поэтому фоновые ответы поставщика используют те же параметры для каждого запуска, которые описаны выше. Конструкция использования не включает автоматически фоновые ответы поставщика: устанавливается AllowBackgroundResponses в .NET, options={"background": True} в Python или agent.AllowBackgroundResponses(true) Go при запуске запуска. Сохраняйте сеанс и сохраняйте маркеры продолжения, когда операция должна выжить после перезапуска процесса.

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

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

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

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

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

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

Дальнейшие действия

RAG