Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
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