Referência de API de agente de longa duração

Esta referência lista a superfície do SDK AgentServer para construir agentes alojados resilientes e de longa duração: as primitivas de tarefas resilientes, as opções de Respostas resilientes e o registo de streaming. Para os conceitos por detrás destas APIs, veja Resiliência para agentes alojados de longa duração. Para guias orientadas para tarefas, consulte os guias práticos.

Packages

As APIs desta página requerem pelo menos as seguintes versões de pacotes geralmente disponíveis.

Protocolo Python (versão mínima) .NET (versão mínima)
Core (tarefas, streaming, armazenamento) azure-ai-agentserver-core ≥ 2.0.0 Azure.AI.AgentServer.Core ≥ 1.0.0
Responses azure-ai-agentserver-responses ≥ 2.0.0 Azure.AI.AgentServer.Responses ≥ 1.0.0
Invocações azure-ai-agentserver-invocations ≥ 1.0.0 Azure.AI.AgentServer.Invocations ≥ 1.0.0

Note

Use a versão mais recente disponível. As versões listadas são os mínimos que incluem a tarefa resiliente, as Respostas resilientes e as APIs de registo de streaming descritas aqui.

Tarefas resilientes

Os primitivos de tarefa tornam uma unidade de trabalho resistente a crashes. O subsistema de tarefas resilientes é opt-in: chamar set_resilient_tasks_enabled(True) antes do arranque do host para que o framework construa e TaskManager execute a varredura de recuperação de arranque (ver Ativar tarefas resilientes).

Declarar uma tarefa

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) Trabalho resiliente de uma vez. Uma entrada produz um resultado.
@multi_turn_task(*, name, title=None, timeout=None, retry=None, steerable=False) Uma cadeia de conversas que permanece suspended entre turnos. Definir steerable=True para colocar um novo turno atrás do ativo.

Executar uma tarefa

# 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 Devoluções Notes
await task.run(*, input, task_id=None, if_last_input_id=None) Output Corre até à conclusão e devolve o resultado.
task.start(*, input, task_id=None, if_last_input_id=None) TaskRun[Output] Devolve um nome que pode esperar ou cancelar.

TaskContext

O manipulador recebe uma TaskContext descrição da tentativa atual.

Python (TaskContext[Input]) C# (TaskContext<T>) Description
input Input O valor que o chamador passou. Persistiu antes do handler correr.
task_id TaskId A identidade profissional duradoura.
input_id InputId A identidade por turno/por entrada.
entry_mode EntryMode fresh, resumed, ou recovered.
metadata Metadata Estado-chave-valor pequeno e duradouro (TaskMetadata).
retry_attempt RetryAttempt 0 à primeira tentativa.
— RecoveryCount Número de recuperações de acidentes nesta tentativa.
is_steered_turn IsSteeredTurn True se esta curva fosse promovida a partir da fila de direção.
pending_input_count PendingInputCount Quantos turnos mais recentes estão em fila.
cancel Cancellation Sinal de cancelamento cooperativo (qualquer causa).
cancel_requested CancelRequested Causa: foi pedido um cancelamento explícito.
timeout_exceeded TimeoutExceeded Causa: o timeout por tarefa disparado.
shutdown Shutdown O contentor está a fechar.
await ctx.exit_for_recovery() await ctx.ExitForRecoveryAsync() Adiar o trabalho inacabado; deixa o disco em curso para uma vida posterior.

entry_mode / EntryMode Valores:

Valor Meaning
fresh / Fresh Primeira execução para isto (task_id, input_id).
resumed / Resumed Uma volta subsequente de uma cadeia já existente.
recovered / Recovered Uma vida anterior fez esta tentativa e não terminou; reativada com a entrada persistente.

TaskRun

A alça devolvida por start / StartAsync.

Python (TaskRun[Output]) C# (TaskRun<T>) Description
task_id TaskId A identidade profissional.
input_id InputId A identidade de entrada.
metadata Metadata Referência de metadados em tempo real durante o voo.
is_queued IsQueued True se esta entrada estivesse colocada atrás de uma curva ativa de direção.
await run.result() await run.GetResultAsync() Aguarde o resultado.
await run.cancel() await run.CancelAsync() Cancela cooperativamente.
await run run.GetAwaiter() Aguardável diretamente.

Política de Re-tentativa

Retentativas aplicam-se a falhas do handler, não à recuperação de crash. A recuperação de falhas reentra na mesma tentativa e não consome o orçamento de retentativas.

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

Fórmula de atraso: min(initial_delay * backoff_coefficient ** attempt, max_delay).

Estado da tarefa e exceções

TaskStatus (C#) / valores de estado: Pending, InProgress, Suspended, Completed.

Exceção Python Exceção C# Criado quando
TaskConflictError TaskConflictException Uma tarefa simultânea não orientável start atingiu uma tarefa em voo.
TaskCancelled TaskCancelledException A corrida foi cancelada.
TaskFailed TaskFailedException O responsável falhou completamente.
TaskDeferred TaskDeferredException O trabalho de recuperação foi adiado.
SteeringQueueFull SteeringQueueFullException A fila de condução está cheia.
LastInputIdPreconditionFailed LastInputIdPreconditionFailedException if_last_input_id / IfLastInputId não combinava.
InputTooLarge InputTooLargeException A entrada excedeu o limite de carga útil da tarefa (~10 MiB).

Permitir tarefas resilientes

O subsistema de tarefas resilientes é opt-in. Chamar set_resilient_tasks_enabled(True) antes do arranque do host (normalmente na altura da importação), constrói AgentServerHost e TaskManager executa a varredura de recuperação de arranque. Sem ela, get_task_manager() levanta TaskManagerNotInitialized e .run().start() / não consegue executar uma tarefa—declarar um @task ou @multi_turn_task não ativa o subsistema por si só.

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

Opções de Respostas Resilientes

Defina o modo ResponsesServerOptions ao construir o hospedeiro. Ambas as bandeiras estão desligadas por defeito.

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,
    ),
)
Python C# Predefinição Description
resilient_background ResilientBackground False Invoca novamente o handler ao reiniciar. Aplica-se apenas a store=true, background=true respostas.
steerable_conversations SteerableConversations False Coloca um turno simultâneo em fila em vez de o rejeitar.
default_fetch_history_count DefaultFetchHistoryCount 100 Itens de histórico máximo hidratados por turno.
sse_keep_alive_interval_seconds — None Intervalo SSE para manter a vida.
shutdown_grace_period_seconds — 10 Segundos para esperar pelo trabalho em voo no encerramento.

Consciente da recuperação ResponseContext

Disponível nos handlers context de resposta quando a resiliência está ativada.

Python C# Description
context.is_recovery IsRecovery True quando o manipulador era reativado após um acidente.
context.persisted_response PersistedResponse O último instantâneo de resposta duradouro e controlado.
context.conversation_chain_metadata ConversationChainMetadata Pequenas referências cruzadas e marcas de água.
— ConversationChainId Identidade estável da cadeia de conversa.
context.is_steered_turn IsSteeredTurn True se esta curva fosse promovida a partir da fila de direção.
context.pending_input_count PendingInputCount Turnos mais recentes à espera na fila.
await context.exit_for_recovery() await ExitForRecoveryAsync() Adiar a recuperação após o encerramento; deixa a resposta in_progress.

Registo de streaming

Escolhe um backing no arranque e depois verifica os streams por um ID por turno.

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()
Configurador Repetição Sobrevive ao reinício
use_in_memory_live() No No
use_in_memory_replay(*, cursor_fn=None, ttl_seconds=None) Sim, dentro do TTL No
use_file_backed_replay(*, storage_dir=None, cursor_fn=None, ttl_seconds=None, serializer=None, deserializer=None) Yes Yes

Operações do registo: await streams.get_or_create(id), await streams.delete(id). Passe cursor_fn para ativar subscribe(after=...) e last_cursor().

Exceções de streaming: EventStreamClosedError/EventStreamClosedException, EventStreamNotFoundError/EventStreamNotFoundException, e a base .EventStreamError/EventStreamException