Uzun süre çalışan aracı API başvurusu (önizleme)

Bu başvuruda, uzun süre çalışan, dayanıklı barındırılan aracılar oluşturmaya yönelik AgentServer SDK yüzeyi listelenir: dayanıklı görev temel bilgileri, dayanıklı Yanıtlar seçenekleri ve akış kayıt defteri. Bu API'lerin arkasındaki kavramlar için bkz. Uzun süre çalışan barındırılan aracılar için dayanıklılık. Görev odaklı izlenecek yollar için nasıl yapılır kılavuzlarına bakın.

Note

Uzun süre çalışan aracılar önizleme aşamasındadır. Bu sayfadaki API'ler paketlerden alınıyor azure-ai-agentserver ve değiştirilebilir.

Packages

Bu sayfadaki API'ler en az aşağıdaki paket sürümlerini gerektirir. Python paketleri genel kullanıma sunulmuştur; .NET paketleri önizleme aşamasındadır; ile yükleyin--prerelease.

Protocol	Python (en düşük sürüm)	.NET (en düşük sürüm)
Çekirdek (görevler, akış, depolama)	azure-ai-agentserver-core ≥ 2.0.0	Azure.AI.AgentServer.Core ≥ 1.0.0-beta.28
Yanıtlar	azure-ai-agentserver-responses ≥ 2.0.0	Azure.AI.AgentServer.Responses ≥ 1.0.0-beta.8
Çağrılar	azure-ai-agentserver-invocations ≥ 1.0.0	Azure.AI.AgentServer.Invocations ≥ 1.0.0-beta.6

Note

Kullanılabilir en son sürümü kullanın. Listelenen sürümler, burada açıklanan dayanıklı görevi, dayanıklı Yanıtları ve akış kayıt defteri API'lerini içeren en düşük değerlerdir.

Dayanıklı görevler

Görev ilkelleri, bir iş birimini kilitlenmeye dayanıklı hale getirir. Dayanıklı görev alt sistemi kabul edilir: ana bilgisayar başlatmadan önce çağırarak set_resilient_tasks_enabled(True) çerçevenin başlatma kurtarma taramasını oluşturmasını TaskManager ve çalıştırmasını sağlar (bkz. Dayanıklı görevleri etkinleştirme).

Görev bildirme

Python

from datetime import timedelta
from azure.ai.agentserver.core.tasks import task, multi_turn_task, TaskContext, RetryPolicy

@task(name="summarize", timeout=timedelta(minutes=10), retry=RetryPolicy())
async def summarize(ctx: TaskContext[str]) -> str:
    ...

@multi_turn_task(name="chat", steerable=True)
async def chat(ctx: TaskContext[dict]) -> dict:
    ...

Decorator	Purpose
@task(*, name, title=None, timeout=None, retry=None)	Tek seferlik dayanıklı iş. Bir giriş bir sonuç üretir.
@multi_turn_task(*, name, title=None, timeout=None, retry=None, steerable=False)	Dönüşler arasında kalan suspended bir konuşma zinciri. Etkin olanın arkasında yeni bir dönüş kuyruğa almak için ayarlayın steerable=True .

C#

using Azure.AI.AgentServer.Core.Tasks;

// Register the task engine, then declare tasks.
builder.Services.AddResilientTasks(credential);

builder.Services.AddResilientTaskBuilder(tasks =>
{
    tasks.AddTask<string, string>("summarize", async (TaskContext<string> ctx, CancellationToken ct) =>
    {
        // ...
        return result;
    });

    tasks.AddMultiTurnTask<ChatInput, ChatOutput>("chat", async (ctx, ct) =>
    {
        // ...
        return output;
    }, steerable: true);
});

Method	Purpose
services.AddResilientTasks(TokenCredential)	Dayanıklı görev altyapısını ve kurtarma tarayıcısını kaydeder.
ResilientTaskBuilder.AddTask<TIn,TOut>(name, handler, configure?)	Tek seferlik dayanıklı çalışmayı bildirir.
ResilientTaskBuilder.AddMultiTurnTask<TIn,TOut>(name, handler, steerable, configure?)	Çok dönüşlü bir zincir bildirir.

Görev çalıştırma

Python

# One-shot: run returns the output directly.
result = await summarize.run(input="...")

# Multi-turn: same task_id resumes the chain; if_last_input_id enforces ordering.
r = await chat.run(task_id="conv-7", input={"msg": "hi"}, if_last_input_id=prev_id)

# Fire-and-track: start returns a TaskRun handle.
run = await chat.start(task_id="conv-7", input={"msg": "hi"})

Call	İadeler	Notlar
await task.run(*, input, task_id=None, if_last_input_id=None)	Output	Tamamlanmaya kadar çalışır ve sonucu döndürür.
task.start(*, input, task_id=None, if_last_input_id=None)	TaskRun[Output]	Bekleyebileceğiniz veya iptal ettiğiniz bir tanıtıcı döndürür.

C#

// Resolve the task and run it.
var run = await task.StartAsync(input, new RunOptions
{
    TaskId = "conv-7",
    IfLastInputId = prevId,
});
var output = await run.GetResultAsync();

RunOptions TaskId, InputIdve IfLastInputId (sipariş önkoşulu) taşır.

TaskContext

İşleyici, geçerli girişimi açıklayan bir TaskContext alır.

Python (TaskContext[Input])	C# (TaskContext<T>)	Description
input	Input	Çağıranın geçtiği değer. İşleyici çalışmadan önce kalıcı hale.
task_id	TaskId	Dayanıklı iş kimliği.
input_id	InputId	Dönüş başına/giriş başına kimlik.
entry_mode	EntryMode	fresh, resumedveya recovered.
metadata	Metadata	Küçük dayanıklı anahtar-değer durumu (TaskMetadata).
retry_attempt	RetryAttempt	İlk denemede 0.
—	RecoveryCount	Bu girişim için kilitlenme kurtarmalarının sayısı.
is_steered_turn	IsSteeredTurn	True bu dönüş direksiyon kuyruğundan yükseltildiyse.
pending_input_count	PendingInputCount	Kuyruğa alınan daha yeni dönüş sayısı.
cancel	Cancellation	İşbirliğine dayalı iptal sinyali (herhangi bir neden).
cancel_requested	CancelRequested	Neden: Açık bir iptal istendi.
timeout_exceeded	TimeoutExceeded	Neden: Görev başına zaman aşımı tetiklenmiş.
shutdown	Shutdown	Kapsayıcı kapatılıyor.
await ctx.exit_for_recovery()	await ctx.ExitForRecoveryAsync()	Tamamlanmamış çalışmayı erteleme; daha sonraki bir yaşam süresi boyunca devam eden kaydı bırakır.

entry_mode / EntryMode değerler:

Değer	Meaning
fresh / Fresh	Bu (task_id, input_id)için ilk yürütme.
resumed / Resumed	Mevcut bir zincirin sonraki dönüşü.
recovered / Recovered	Önceki bir yaşam süresi bu girişimi çalıştırdı ve tamamlamadım; kalıcı giriş ile yeniden çağrılır.

TaskRun

tarafından start / StartAsyncdöndürülen tanıtıcı.

Python (TaskRun[Output])	C# (TaskRun<T>)	Description
task_id	TaskId	İş kimliği.
input_id	InputId	Giriş kimliği.
metadata	Metadata	Uçuş sırasında canlı meta veri başvurusu.
is_queued	IsQueued	True bu giriş etkin bir yönlendirilebilir dönüş arkasında kuyruğa alınmışsa.
await run.result()	await run.GetResultAsync()	Çıktıyı bekle.
await run.cancel()	await run.CancelAsync()	İşbirliğiyle iptal et.
await run	run.GetAwaiter()	Doğrudan beklenebilir.

Yeniden deneme ilkesi

Yeniden denemeler, kilitlenme kurtarma için değil işleyici hatalarına uygulanır. Kilitlenme kurtarma aynı denemeyi yeniden girer ve yeniden deneme bütçesini kullanmaz.

Python

from azure.ai.agentserver.core.tasks import RetryPolicy

RetryPolicy(
    initial_delay=timedelta(seconds=1),   # base delay
    backoff_coefficient=2.0,              # multiplier per attempt (>= 1.0)
    max_delay=timedelta(seconds=60),      # cap
    max_attempts=3,                       # total tries, including the first
)
RetryPolicy.no_retry()                    # single attempt

Gecikme formülü: min(initial_delay * backoff_coefficient ** attempt, max_delay).

C#

TaskRetryPolicy.ExponentialBackoff(maxAttempts: 3, initialDelay: TimeSpan.FromSeconds(1),
    backoffCoefficient: 2.0, maxDelay: TimeSpan.FromSeconds(60), jitter: true);
TaskRetryPolicy.FixedDelay(maxAttempts, delay, jitter);
TaskRetryPolicy.LinearBackoff(maxAttempts, initialDelay, increment, maxDelay, jitter);
TaskRetryPolicy.NoRetry;

Özellikler: InitialDelay, BackoffCoefficient, MaxDelay, MaxAttempts, Jitter, RetryOn.

Görev durumu ve özel durumlar

TaskStatus (C#) / durum değerleri: Pending, InProgress, Suspended, Completed.

Python özel durumu	C# özel durumu	Yükseltildiğinde
TaskConflictError	TaskConflictException	Eşzamanlı yönlendirilemez start bir görev, bir uçuş içi göreve isabet etti.
TaskCancelled	TaskCancelledException	Çalıştırma iptal edildi.
TaskFailed	TaskFailedException	İşleyici son olarak başarısız oldu.
TaskDeferred	TaskDeferredException	çalışma kurtarma için ertelendi.
SteeringQueueFull	SteeringQueueFullException	Direksiyon kuyruğu kapasitede.
LastInputIdPreconditionFailed	LastInputIdPreconditionFailedException	if_last_input_id / IfLastInputId eşleşmedi.
InputTooLarge	InputTooLargeException	Giriş, görev yükü sınırını (~10 MiB) aştı.

Dayanıklı görevleri etkinleştirme

Dayanıklı görev alt sistemi kabul edilir. Konak başlatmadan önce (genellikle içeri aktarma zamanında) AgentServerHostTaskManager çağrısı set_resilient_tasks_enabled(True) yapın ve başlangıç kurtarma taramasını çalıştırın. Bu olmadan, get_task_manager() bir görevi yükseltir TaskManagerNotInitialized ve .run().start() / çalıştıramaz; @task veya bildiriminde bulunur ve @multi_turn_task alt sistemi tek başına etkinleştirmez.

Python

from azure.ai.agentserver.core.tasks import set_resilient_tasks_enabled
set_resilient_tasks_enabled(True)   # call at import time, before host startup

C#

AddResilientTasks(credential) ana bilgisayar başlatma sırasında kurtarma tarayıcısını kaydeder; ayrı bir anahtar gerekmez.

Dayanıklı Yanıtlar seçenekleri

Konağı oluştururken açık ResponsesServerOptions olarak ayarlayın. Her iki bayrak da varsayılan olarak kapalı olarak işaretlenir.

Python

from azure.ai.agentserver.responses import ResponsesAgentServerHost, ResponsesServerOptions

app = ResponsesAgentServerHost(
    options=ResponsesServerOptions(
        resilient_background=True,       # re-invoke stored background responses after a crash
        steerable_conversations=True,    # queue a new turn instead of 409 conversation_locked
        default_fetch_history_count=100,
        sse_keep_alive_interval_seconds=None,
        shutdown_grace_period_seconds=10,
    ),
)

C#

var options = new ResponsesServerOptions
{
    ResilientBackground = true,
    SteerableConversations = true,
    DefaultFetchHistoryCount = 100,
};

Python	C#	Varsayılan	Description
resilient_background	ResilientBackground	False	yeniden başlatmada işleyiciyi yeniden çağırın. Yalnızca store=trueiçin geçerlidir, background=true yanıtlar.
steerable_conversations	SteerableConversations	False	Eşzamanlı dönüşleri reddetmek yerine kuyruğa alın.
default_fetch_history_count	DefaultFetchHistoryCount	100	Dönüş başına nemlendirilmiş en fazla geçmiş öğesi.
sse_keep_alive_interval_seconds	—	None	SSE etkin tutma aralığı.
shutdown_grace_period_seconds	—	10	Kapatma işleminin uçuş içi çalışmasını beklemek için saniyeler.

Kurtarma özellikli ResponseContext

Dayanıklılık etkinleştirildiğinde yanıt işleyicisinde context kullanılabilir.

Python	C#	Description
context.is_recovery	IsRecovery	True bir kilitlenmeden sonra işleyici yeniden çağrıldığında.
context.persisted_response	PersistedResponse	Son durably checkpointed yanıt anlık görüntüsü.
context.conversation_chain_metadata	ConversationChainMetadata	Küçük çapraz dönüş başvuruları ve filigranları.
—	ConversationChainId	Konuşma zincirinin kararlı kimliği.
context.is_steered_turn	IsSteeredTurn	True bu dönüş direksiyon kuyruğundan yükseltildiyse.
context.pending_input_count	PendingInputCount	Daha yenisi kuyrukta beklerken döner.
await context.exit_for_recovery()	await ExitForRecoveryAsync()	Kapatılırken kurtarma için erteleme; yanıtını in_progressbırakır.

Akış kayıt defteri

Başlangıçta bir yedekleme seçin, ardından akışlara dönüş başına kimlikle bakın.

Python

from azure.ai.agentserver.core.streaming import streams

streams.use_in_memory_live()                                        # no replay, no restart survival
streams.use_in_memory_replay(cursor_fn=lambda e: e["n"], ttl_seconds=600)
streams.use_file_backed_replay(storage_dir=Path("/streams"),
                               cursor_fn=lambda e: e["n"])

stream = await streams.get_or_create(invocation_id)
await stream.emit({"n": 0, "delta": "..."})
async for event in stream.subscribe(after=last_cursor):
    ...
await stream.close()

Yapılandırıcı	Tekrar Oynat	Yeniden başlatmaya devam eder
use_in_memory_live()	Hayır	Hayır
use_in_memory_replay(*, cursor_fn=None, ttl_seconds=None)	Evet, TTL içinde	Hayır
use_file_backed_replay(*, storage_dir=None, cursor_fn=None, ttl_seconds=None, serializer=None, deserializer=None)	Yes	Yes

Kayıt defteri işlemleri: await streams.get_or_create(id), await streams.delete(id). ve last_cursor()'yi etkinleştirmek subscribe(after=...) için geçirincursor_fn.

C#

using Azure.AI.AgentServer.Core.Streaming;

builder.Services.AddEventStreams(options =>
{
    // Configure the backing (live / replay / file-backed) via EventStreamOptions.
});

// Resolve the registry and obtain a per-turn stream.
EventStream stream = await registry.GetOrCreateAsync(invocationId);

Yedeklemeler: BroadcastEventStream (canlı), ReplayEventStream (bellek içi yeniden yürütme), FileBackedReplayEventStream (kalıcı). Kayıt Defteri: EventStreamRegistry / InMemoryEventStreamRegistry.

Akış özel durumları: EventStreamClosedError/EventStreamClosedException,EventStreamNotFoundException/EventStreamNotFoundError ve tabanı.EventStreamError/EventStreamException

İlgili içerik

• Uzun süre çalışan barındırılan aracılar için dayanıklılık
• Kilitlenmeden sonra uzun süre çalışan işleri kurtarma
• Uçuş içi temsilci dönüşlerini yönlendirme
• Yeniden bağlanarak uzun süre çalışan aracı çıkışını akışla aktarın
• Uzun süre çalışan aracılar için durumu yönetme
• Barındırılan aracılar için dayanıklı durum deposu