Aracılığıyla paylaş

Yazılım Temsilcisi Arka Plan Yanıtları

Microsoft Agent Framework, tamamlanması zaman alabilen uzun süre çalışan işlemleri işlemek için arka plan yanıtlarını destekler. Bu özellik, aracıların bir isteği işlemeye başlamasını ve sonuçları yoklamak veya kesintiye uğrayan akışları sürdürmek için kullanılabilecek bir devamlılık belirteci döndürmesini sağlar.

Tip

Tam bir çalışma örneği için Bkz. Arka Plan Yanıtları örneği.

Arka Plan Yanıtları Ne Zaman Kullanılır?

Arka plan yanıtları özellikle şunlar için kullanışlıdır:

  • Önemli işleme süresi gerektiren karmaşık akıl yürütme görevleri
  • Ağ sorunları veya istemci zaman aşımları nedeniyle kesintiye uğrayabilecek işlemler
  • Uzun süre çalışan bir görevi başlatmak ve sonuçları daha sonra yeniden denetlemek istediğiniz senaryolar

Arka Plan Yanıtları Nasıl Çalışır?

Arka plan yanıtları, uzun süre çalışan işlemleri işlemek için bir devamlılık belirteci mekanizması kullanır. Arka plan yanıtları etkinleştirilmiş bir aracıya istek gönderdiğinizde iki işlemden biri gerçekleşir:

  1. Hemen tamamlama: Aracı görevi hızlı bir şekilde tamamlar ve devam belirteci olmadan son yanıtı döndürür
  2. Arka plan işleme: Aracı arka planda işlemeye başlar ve nihai sonuç yerine bir devamlılık belirteci döndürür

Devamlılık belirteci, akışsız aracı API'sini kullanarak tamamlanmak üzere yoklama yapmak veya akış aracısı API'si ile kesintiye uğrayan bir akışı sürdürmek için gerekli tüm bilgileri içerir. Devamlılık belirteci olduğunda nullişlem tamamlanır. Bu, bir arka plan yanıtı tamamlandığında, başarısız olduğunda veya daha fazla ilerleyemediğinde (örneğin, kullanıcı girişi gerektiğinde) gerçekleşir.

Arka Plan Yanıtlarını Etkinleştirme

Arka plan yanıtlarını etkinleştirmek için içinde özelliğini AllowBackgroundResponsestrueolarak ayarlayınAgentRunOptions:

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

Uyarı

Şu anda yalnızca OpenAI Yanıtları API'sini kullanan aracılar arka plan yanıtlarını destekler: OpenAI Yanıt Aracısı ve Azure OpenAI Yanıt Aracısı.

Bazı aracılar arka plan yanıtları üzerinde açık denetime izin vermeyebilir. Bu aracılar, ayardan bağımsız olarak işlemin karmaşıklığı temelinde bir arka plan yanıtı başlatıp başlatmayacağına AllowBackgroundResponses otonom olarak karar verebilir.

AkışSız Arka Plan Yanıtları

Akış dışı senaryolarda, bir aracıyı ilk kez çalıştırdığınızda bir devamlılık belirteci döndürebilir veya döndürmeyebilir. Devam belirteci döndürülmezse, işlem tamamlanmıştır. Bir devamlılık belirteci döndürülürse, aracının işlemeye devam eden bir arka plan yanıtı başlattığını ve nihai sonucu almak için yoklama gerektirdiğini gösterir:

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

Uyarı

DefaultAzureCredential geliştirme için uygundur ancak üretimde dikkatli bir şekilde dikkate alınması gerekir. Üretimde gecikme sorunları, istenmeyen kimlik bilgisi yoklama ve geri dönüş mekanizmalarından kaynaklanan olası güvenlik risklerini önlemek için belirli bir kimlik bilgisi (ör ManagedIdentityCredential. ) kullanmayı göz önünde bulundurun.

Önemli Noktalar:

  • İlk çağrı hemen tamamlanabilir (devam belirteci yok) veya bir arka plan işlemi başlatabilir (devamlılık belirteci ile)
  • Devam belirteci döndürülmezse işlem tamamlanır ve yanıt son sonucu içerir
  • Bir devamlılık belirteci döndürülürse aracı yoklama gerektiren bir arka plan işlemi başlatmıştır
  • Sonraki yoklama çağrılarında önceki yanıttan devam belirtecini kullanın
  • olduğunda ContinuationTokennullişlem tamamlanır

Arka Plan Yanıtlarını Akışla Aktarma

Akış senaryolarında arka plan yanıtları normal akış yanıtları gibi çalışır. Aracı tüm güncelleştirmeleri gerçek zamanlı olarak tüketicilere geri akışla gönderir. Ancak temel fark, özgün akışın kesintiye uğraması durumunda aracıların devamlılık belirteçleri aracılığıyla akışın yeniden başlatılmasını desteklemesidir. Her güncelleştirme, geçerli durumu yakalayan bir devamlılık belirteci içerir ve bu belirteç sonraki akış API çağrılarına geçirilerek akışın kaldığı yerden devam etmesini sağlar:

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

Önemli Noktalar:

  • Her AgentResponseUpdate birinin devamı için kullanılabilecek bir devamlılık belirteci vardır
  • Kesintiden önce alınan son güncelleştirmeden devam belirtecini depolayın
  • Akışı kesinti noktasından sürdürmek için depolanan devamlılık belirtecini kullanın

Tip

Çalıştırılabilir örneklerin tamamı için .NET örneklerine bakın.

Tip

Tam bir çalışma örneği için Bkz. Arka Plan Yanıtları örneği.

Arka Plan Yanıtlarını Etkinleştirme

Arka plan yanıtlarını etkinleştirmek için çağrısı agent.run()yaparken seçeneğini geçirinbackground:

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

Uyarı

Şu anda yalnızca OpenAI Yanıtları API'sini kullanan aracılar arka plan yanıtlarını destekler: OpenAI Yanıt Aracısı ve Azure OpenAI Yanıt Aracısı.

AkışSız Arka Plan Yanıtları

Akış dışı senaryolarda, ile background=Trueilk kez bir aracı çalıştırdığınızda, ile hemen continuation_tokendöndürülebilir. ise continuation_tokenNone, işlem tamamlanmıştır. Aksi takdirde, sonraki çağrılarda belirteci geri geçirerek yoklama:

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)

Önemli Noktalar

  • İlk çağrı hemen tamamlanabilir (devam belirteci yok) veya bir arka plan işlemi başlatabilir (devamlılık belirteci ile)
  • continuation_token Sonraki yoklama çağrılarında önceki yanıttan gelen öğesini kullanın
  • olduğunda continuation_tokenNoneişlem tamamlanır

Arka Plan Yanıtlarını Akışla Aktarma

Akış senaryolarında arka plan yanıtları normal akış gibi çalışır; aracı akışları gerçek zamanlı olarak geri güncelleştirilir. Önemli fark, her güncelleştirmenin bir continuation_tokeniçermesi ve bağlantı kesilirse akış yeniden başlatılmasını etkinleştirmesidir:

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

Kesintiye Uğrayan Akışı Devam Ettiriyor

Akış kesintiye uğrarsa kaldığınız yerden devam etmek için sonuncuyu continuation_token kullanın:

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)

Önemli Noktalar

  • Her AgentResponseUpdate birinde continuation_token bir resumption
  • Kesintiden önce alınan son güncelleştirmedeki belirteci depolama
  • Devam etmek için depolanan belirteci üzerinden geçirin options={"continuation_token": token}

En İyi Yöntemler

Arka plan yanıtları ile çalışırken aşağıdaki en iyi yöntemleri göz önünde bulundurun:

  • Hizmetin aşırıya kaçmasını önlemek için uygun yoklama aralıklarını uygulama
  • İşlem beklenenden uzun sürüyorsa yoklama aralıkları için üstel geri alma kullanın
  • İşlemenin ne zaman tamamleneceğini belirlemek için null her zaman devamlılık belirteçlerini denetleyin
  • Kullanıcı oturumlarına yayılabilen işlemler için devamlılık belirteçlerini kalıcı olarak depolamayı göz önünde bulundurun

Sınırlamalar ve Önemli Noktalar

  • Arka plan yanıtları, uzun süre çalışan işlemleri destekleyen temel yapay zeka hizmetine bağlıdır
  • Tüm aracı türleri arka plan yanıtlarını desteklemeyebilir
  • Ağ kesintileri veya istemci yeniden başlatmaları, devamlılık belirteçlerini kalıcı hale getirmek için özel işleme gerektirebilir

Sonraki Adımlar

BEZ

  • Last updated on