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

Essa referência lista a superfície do SDK do AgentServer para criar agentes hospedados resilientes e de execução longa: os primitivos de tarefa resilientes, as opções de Respostas resilientes e o registro de streaming. Para obter os conceitos por trás dessas APIs, consulte Resiliência para agentes hospedados de longa execução. Para obter instruções passo a passo orientadas a tarefas, consulte os guias de instruções.

Packages

As APIs nesta página exigem pelo menos as seguintes versões de pacote disponíveis.

Protocolo Python (versão mínima) .NET (versão mínima)
Núcleo (tarefas, streaming, armazenamento) azure-ai-agentserver-core ≥ 2.0.0 Azure.AI.AgentServer.Core ≥ 1.0.0
Respostas 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, respostas resilientes e APIs de registro de streaming descritas aqui.

Tarefas resilientes

Os primitivos de tarefa tornam uma unidade de trabalho resiliente a falhas. O subsistema de tarefa resiliente é opt-in: chame set_resilient_tasks_enabled(True) antes da inicialização do host para que a estrutura construa e TaskManager execute a verificação de recuperação de inicialização (consulte Habilitar 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 um tiro só. Uma entrada produz um resultado.
@multi_turn_task(*, name, title=None, timeout=None, retry=None, steerable=False) Uma cadeia de conversas que permanece entre turnos suspended . Defina steerable=True para enfileirar uma nova curva atrás da ativa.

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 Returns Observações
await task.run(*, input, task_id=None, if_last_input_id=None) Output É executado até a conclusão e retorna o resultado.
task.start(*, input, task_id=None, if_last_input_id=None) TaskRun[Output] Retorna um identificador que você pode aguardar ou cancelar.

TaskContext

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

Python (TaskContext[Input]) C# (TaskContext<T>) Description
input Input O valor passado pelo chamador. Persistido antes da execução do manipulador.
task_id TaskId A identidade de trabalho durável.
input_id InputId A identidade por turno/por entrada.
entry_mode EntryMode fresh, resumed ou recovered.
metadata Metadata Estado de chave-valor durável pequeno (TaskMetadata).
retry_attempt RetryAttempt 0 na primeira tentativa.
— RecoveryCount Número de recuperações de falha para esta tentativa.
is_steered_turn IsSteeredTurn True se essa curva foi promovida da fila de direção.
pending_input_count PendingInputCount Quantas voltas mais recentes são enfileiradas.
cancel Cancellation Sinal de cancelamento cooperativo (qualquer causa).
cancel_requested CancelRequested Causa: um cancelamento explícito foi solicitado.
timeout_exceeded TimeoutExceeded Causa: o tempo limite por tarefa disparado.
shutdown Shutdown O contêiner está sendo desligado.
await ctx.exit_for_recovery() await ctx.ExitForRecoveryAsync() Adiar o trabalho inacabado; deixa o registro em andamento para um tempo de vida posterior.

entry_mode / EntryMode valores:

Valor Significado
fresh / Fresh Primeira execução para isso (task_id, input_id).
resumed / Resumed Uma reviravolta subsequente de uma cadeia existente.
recovered / Recovered Um tempo de vida anterior executou essa tentativa e não terminou; invocado novamente com a entrada persistente.

TaskRun

O identificador retornado por start / StartAsync.

Python (TaskRun[Output]) C# (TaskRun<T>) Description
task_id TaskId A identidade de trabalho.
input_id InputId A identidade de entrada.
metadata Metadata Referência de metadados ao vivo durante o voo.
is_queued IsQueued True se essa entrada foi enfileirada atrás de uma curva de direção ativa.
await run.result() await run.GetResultAsync() Aguarde a saída.
await run.cancel() await run.CancelAsync() Cancelar cooperativamente.
await run run.GetAwaiter() Aguardado diretamente.

Política de nova tentativa

As novas tentativas se aplicam a falhas do manipulador, não à recuperação de falhas. A recuperação de falha reinsere a mesma tentativa e não consome o orçamento de repetição.

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

Status da tarefa e exceções

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

Python exceção Exceção de C# Gerado quando
TaskConflictError TaskConflictException Um não-direcional start simultâneo atingiu uma tarefa em vôo.
TaskCancelled TaskCancelledException A execução foi cancelada.
TaskFailed TaskFailedException O manipulador falhou terminalmente.
TaskDeferred TaskDeferredException O trabalho foi adiado para recuperação.
SteeringQueueFull SteeringQueueFullException A fila de direção está em capacidade.
LastInputIdPreconditionFailed LastInputIdPreconditionFailedException if_last_input_id / IfLastInputId não correspondeu.
InputTooLarge InputTooLargeException A entrada excedeu o limite de carga da tarefa (aproximadamente 10 MiB).

Habilitar tarefas resilientes

O subsistema de tarefa resiliente é opt-in. Chame set_resilient_tasks_enabled(True) antes da inicialização do host (normalmente no momento da importação) para AgentServerHost construir e TaskManager executar a verificação de recuperação de inicialização. Sem ela, get_task_manager() gera TaskManagerNotInitialized e .run().start() / não pode executar uma tarefa , declarando ou @task@multi_turn_task não habilitando o subsistema por conta própria.

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 ao ResponsesServerOptions construir o host. Ambos os sinalizadores são desativados por padrão.

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# Default Description
resilient_background ResilientBackground False Reinvoque o manipulador na reinicialização. Aplica-se somente a store=truebackground=true respostas.
steerable_conversations SteerableConversations False Enfileirar uma curva simultânea em vez de rejeitá-la.
default_fetch_history_count DefaultFetchHistoryCount 100 Máximo de itens de histórico hidratados por turno.
sse_keep_alive_interval_seconds — None Intervalo de keep-alive da SSE.
shutdown_grace_period_seconds — 10 Segundos para esperar pelo trabalho em vôo no desligamento.

Reconhecimento de recuperação ResponseContext

Disponível no manipulador de context resposta quando a resiliência está habilitada.

Python C# Description
context.is_recovery IsRecovery True quando o manipulador foi invocado novamente após uma falha.
context.persisted_response PersistedResponse O último instantâneo de resposta com ponto de verificação durável.
context.conversation_chain_metadata ConversationChainMetadata Pequenas referências de curva cruzada e marcas d'água.
— ConversationChainId Identidade estável da cadeia de conversa.
context.is_steered_turn IsSteeredTurn True se essa curva foi promovida da fila de direção.
context.pending_input_count PendingInputCount As voltas mais recentes são aguardadas na fila.
await context.exit_for_recovery() await ExitForRecoveryAsync() Adiar para recuperação no desligamento; deixa a resposta in_progress.

Registro de streaming

Escolha um backup na inicialização e procure fluxos por 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 Replay Sobrevive à reinicialização
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) Sim Sim

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

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