Respons Latar Belakang Agen

Microsoft Agent Framework mendukung respons latar belakang untuk menangani operasi jangka panjang yang mungkin membutuhkan waktu untuk diselesaikan. Fitur ini memungkinkan agen untuk mulai memproses permintaan dan mengembalikan token kelanjutan yang dapat digunakan untuk melakukan polling untuk hasil atau melanjutkan aliran yang terganggu.

Tip

Untuk contoh kerja lengkap, lihat sampel Respons Latar Belakang.

Kapan Menggunakan Respons Latar Belakang

Respons latar belakang sangat berguna untuk:

  • Tugas penalaran kompleks yang membutuhkan waktu pemrosesan yang signifikan
  • Operasi yang mungkin terganggu oleh masalah jaringan atau batas waktu klien
  • Skenario di mana Anda ingin memulai tugas yang berjalan lama dan memeriksa kembali nanti untuk hasilnya

Cara Kerja Respons Latar Belakang

Respons latar belakang menggunakan mekanisme token kelanjutan untuk menangani operasi yang berjalan lama. Saat Anda mengirim permintaan ke agen dengan respons latar belakang diaktifkan, salah satu dari dua hal terjadi:

  1. Penyelesaian segera: Agen menyelesaikan tugas dengan cepat dan mengembalikan respons akhir tanpa token kelanjutan
  2. Pemrosesan latar belakang: Agen mulai memproses di latar belakang dan mengembalikan token kelanjutan alih-alih hasil akhir

Token kelanjutan berisi semua informasi yang diperlukan untuk polling untuk penyelesaian menggunakan API agen non-streaming atau melanjutkan aliran yang terganggu dengan API agen streaming. Token yang tidak ada (null dalam .NET, None dalam Python, atau string kosong di Go) berarti operasi telah selesai, gagal, atau tidak dapat melanjutkan lebih lanjut, misalnya, ketika input pengguna diperlukan.

Mengaktifkan Respons Latar Belakang

Untuk mengaktifkan respons latar belakang, atur properti ke AllowBackgroundResponsestrue di AgentRunOptions:

using Microsoft.Agents.AI;

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

Nota

Saat ini, hanya agen yang menggunakan OPENAI Responses API yang mendukung respons latar belakang: OpenAI Responses Agent dan Azure OpenAI Responses Agent.

Beberapa agen mungkin tidak mengizinkan kontrol eksplisit atas respons latar belakang. Agen-agen ini dapat memutuskan secara otonom apakah akan memulai respons latar belakang berdasarkan kompleksitas operasi, terlepas dari pengaturannya AllowBackgroundResponses .

Respons Latar Belakang Non-Streaming

Untuk skenario non-streaming, ketika Anda awalnya menjalankan agen, itu mungkin atau mungkin tidak mengembalikan token kelanjutan. Jika tidak ada token kelanjutan yang dikembalikan, itu berarti operasi telah selesai. Jika token kelanjutan dikembalikan, itu menunjukkan bahwa agen telah memulai respons latar belakang yang masih diproses dan akan memerlukan polling untuk mengambil hasil akhir:

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);

Warning

DefaultAzureCredential nyaman untuk pengembangan tetapi membutuhkan pertimbangan yang cermat dalam produksi. Dalam produksi, pertimbangkan untuk menggunakan kredensial tertentu (misalnya, ManagedIdentityCredential) untuk menghindari masalah latensi, pemeriksaan kredensial yang tidak diinginkan, dan potensi risiko keamanan dari mekanisme fallback.

Poin Utama:

  • Panggilan awal dapat segera selesai (tidak ada token kelanjutan) atau memulai operasi latar belakang (dengan token kelanjutan)
  • Jika tidak ada token kelanjutan yang dikembalikan, operasi selesai dan respons berisi hasil akhir
  • Jika token kelanjutan dikembalikan, agen telah memulai proses latar belakang yang memerlukan polling
  • Gunakan token kelanjutan dari respons sebelumnya dalam panggilan polling berikutnya
  • Ketika ContinuationToken adalah null, operasi selesai

Respons Latar Belakang Streaming

Dalam skenario streaming, respons latar belakang berfungsi seperti respons streaming reguler - agen mengalirkan semua pembaruan kembali ke konsumen secara real time. Namun, perbedaan utamanya adalah bahwa jika aliran asli terganggu, agen mendukung penerbitan ulang aliran melalui token kelanjutan. Setiap pembaruan mencakup token kelanjutan yang menangkap status saat ini, memungkinkan aliran dilanjutkan dari tempat yang ditinggalkannya dengan meneruskan token ini ke panggilan API streaming berikutnya:

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

Poin Utama:

  • Masing-masing AgentResponseUpdate berisi token kelanjutan yang dapat digunakan untuk dimulai kembali
  • Simpan token kelanjutan dari pembaruan terakhir yang diterima sebelum gangguan
  • Gunakan token kelanjutan tersimpan untuk melanjutkan aliran dari titik gangguan

Tip

Lihat sampel .NET untuk contoh lengkap yang dapat dijalankan.

Tip

Untuk contoh kerja lengkap, lihat sampel Respons Latar Belakang.

Mengaktifkan Respons Latar Belakang

Untuk mengaktifkan respons latar belakang, berikan background opsi saat memanggil agent.run():

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

Nota

Python agen yang didukung oleh OpenAI Responses API, Azure OpenAI Responses API, atau Microsoft Foundry mendukung respons latar belakang.

Dengan FoundryChatClient, respons latar belakang dapat menjalankan alat fungsi lokal dengan penyimpanan respons sisi penyedia (store=True) atau pemutaran ulang tanpa status (store=False). Pertahankan sesi yang sama saat polling sehingga respons yang dilanjutkan dapat melanjutkan perulangan alat lokal.

Respons Latar Belakang Non-Streaming

Untuk skenario non-streaming, ketika Anda awalnya menjalankan agen dengan background=True, itu dapat segera kembali dengan continuation_token. Jika continuation_token adalah None, operasi telah selesai. Jika tidak, jajak pendapat dengan meneruskan token kembali dalam panggilan berikutnya:

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)

Poin Penting

  • Panggilan awal dapat segera selesai (tidak ada token kelanjutan) atau memulai operasi latar belakang (dengan token kelanjutan)
  • continuation_token Gunakan dari respons sebelumnya dalam panggilan polling berikutnya
  • Ketika continuation_token adalah None, operasi selesai

Respons Latar Belakang Streaming

Dalam skenario streaming, respons latar belakang berfungsi seperti streaming reguler - agen mengalirkan pembaruan kembali secara real time. Perbedaan utamanya adalah bahwa setiap pembaruan menyertakan continuation_token, memungkinkan penerbitan ulang aliran jika koneksi terganggu:

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

Memulai Kembali Aliran yang Terganggu

Jika aliran terganggu, gunakan yang terakhir continuation_token untuk melanjutkan dari tempat aliran ditinggalkan:

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)

Poin Penting

  • Masing-masing AgentResponseUpdate berisi continuation_token untuk dimuat ulang
  • Simpan token dari pembaruan terakhir yang diterima sebelum gangguan
  • Meneruskan token yang disimpan melalui options={"continuation_token": token} untuk melanjutkan

Mengaktifkan respons latar belakang

Teruskan agent.AllowBackgroundResponses(true) saat memulai eksekusi, dan gunakan kembali sesi eksplisit melalui agent.WithSession(session). Penyedia dan penyebaran harus mendukung eksekusi latar belakang; mengatur opsi tidak membuat setiap agen asinkron.

Respons latar belakang non-streaming

Mulai operasi, lalu polling sementara response.ContinuationToken tidak kosong. Lanjutkan dengan a.Run(ctx, nil, ...), bukan RunText: panggilan kelanjutan tidak boleh berisi pesan baru.

Sampel Azure Respons OpenAI yang dipertahankan mengikat operasi dengan batas waktu, menunggu di antara polling, dan segera berhenti pada pembatalan:

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

Atur AZURE_OPENAI_ENDPOINT dan AZURE_OPENAI_DEPLOYMENT_NAME, dan autentikasi dengan kredensial Azure sebelum menjalankan sampel ini. Ini mencetak respons selesai setelah polling selesai. Respons yang segera selesai tidak memiliki token kelanjutan dan tidak memerlukan polling.

Respons latar belakang streaming

Mulai eksekusi streaming dengan agent.Stream(true) dan agent.AllowBackgroundResponses(true). Pertahankan token kelanjutan dari pembaruan terakhir yang Anda terima. Jika koneksi terganggu, lanjutkan tanpa pesan baru:

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

Lanjutkan hanya saat token yang disimpan tidak kosong. Pertahankan sesi dan token dalam penyimpanan aplikasi jika operasi harus bertahan dari proses restart.

Menggunakan respons latar belakang dengan Harness Agent

Agen Harness tetap menjadi agen Agent Framework standar, sehingga respons latar belakang penyedia menggunakan opsi per-eksekusi yang sama yang didokumenkan di atas. Konstruksi Harness tidak mengaktifkan respons latar belakang penyedia secara otomatis: diatur AllowBackgroundResponses dalam .NET, options={"background": True} di Python, atau agent.AllowBackgroundResponses(true) di Go saat memulai eksekusi. Pertahankan sesi dan pertahankan token kelanjutan ketika operasi harus bertahan dari proses mulai ulang.

Ini terpisah dari agen latar belakang, yang mendelegasikan pekerjaan ke agen turunan daripada melanjutkan satu permintaan penyedia.

Praktik Terbaik

Saat bekerja dengan respons latar belakang, pertimbangkan praktik terbaik berikut:

  • Menerapkan interval polling yang sesuai untuk menghindari kewalahan layanan
  • Gunakan backoff eksponensial untuk interval polling jika operasi memakan waktu lebih lama dari yang diharapkan
  • Periksa token kelanjutan yang tidak ada (null, , Noneatau string Go kosong) untuk menentukan kapan pemrosesan selesai
  • Pertimbangkan untuk menyimpan token kelanjutan secara terus-menerus untuk operasi yang dapat mencakup sesi pengguna

Batasan dan Pertimbangan

  • Respons latar belakang bergantung pada layanan AI yang mendasar yang mendukung operasi jangka panjang
  • Tidak semua jenis agen dapat mendukung respons latar belakang
  • Gangguan jaringan atau mulai ulang klien mungkin memerlukan penanganan khusus untuk mempertahankan token kelanjutan

Langkah berikutnya

RAG

  • Terakhir diperbarui pada