Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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
Conteúdo relacionado
- Resiliência para agentes hospedados de longa execução
- Recuperar o trabalho de execução prolongada após uma falha
- Orientar uma curva de agente no voo
- Transmitir saída de agente de execução longa com reconexão
- Gerenciar o estado para agentes de execução prolongada
- Repositório de estado durável para agentes hospedados