Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
En esta referencia se muestra la superficie del SDK de AgentServer para crear agentes hospedados resistentes y de larga duración: las primitivas de tareas resistentes, las opciones respuestas resistentes y el registro de streaming. Para conocer los conceptos subyacentes a estas API, consulte Resilience for long-running hosted agents (Resistencia para agentes hospedados de larga duración). Para ver tutoriales orientados a tareas, consulte las guías paso a paso.
Packages
Las API de esta página requieren al menos las siguientes versiones de paquete disponibles con carácter general.
| Protocolo | Python (versión mínima) | .NET (versión mínima) |
|---|---|---|
| Core (tareas, streaming, almacenamiento) |
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 |
| Invocaciones |
azure-ai-agentserver-invocations ≥ 1.0.0 |
Azure.AI.AgentServer.Invocations ≥ 1.0.0 |
Note
Use la versión más reciente disponible. Las versiones enumeradas son los mínimos que incluyen la tarea resistente, las respuestas resistentes y las API del registro de streaming que se describen aquí.
Tareas resistentes
Las primitivas de tarea hacen que una unidad de trabajo sea resistente al bloqueo. El subsistema de tareas resistentes es opcional: llamada set_resilient_tasks_enabled(True) antes del inicio del host para que el marco construya y TaskManager ejecute el examen de recuperación de inicio (consulte Habilitación de tareas resistentes).
Declarar una tarea
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:
...
| Decorador | propósito |
|---|---|
@task(*, name, title=None, timeout=None, retry=None) |
Trabajo resistente de una sola toma. Una entrada genera un resultado. |
@multi_turn_task(*, name, title=None, timeout=None, retry=None, steerable=False) |
Cadena de conversación que permanece entre turnos suspended . Establezca steerable=True en poner en cola un nuevo turno detrás del activo. |
Ejecución de una tarea
# 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 | Devoluciones | Notas |
|---|---|---|
await task.run(*, input, task_id=None, if_last_input_id=None) |
Output |
Se ejecuta hasta la finalización y devuelve el resultado. |
task.start(*, input, task_id=None, if_last_input_id=None) |
TaskRun[Output] |
Devuelve un identificador que puede esperar o cancelar. |
TaskContext
El controlador recibe un TaskContext que describe el intento actual.
Python (TaskContext[Input]) |
C# (TaskContext<T>) |
Descripción |
|---|---|---|
input |
Input |
Valor que ha pasado el autor de la llamada. Se conserva antes de que se ejecute el controlador. |
task_id |
TaskId |
Identidad de trabajo duradera. |
input_id |
InputId |
Identidad por turno/por entrada. |
entry_mode |
EntryMode |
fresh, resumed, o recovered. |
metadata |
Metadata |
Pequeño estado clave-valor duradero (TaskMetadata). |
retry_attempt |
RetryAttempt |
0 en el primer intento. |
| — | RecoveryCount |
Número de recuperaciones de bloqueo para este intento. |
is_steered_turn |
IsSteeredTurn |
True si este turno fue promocionado desde la cola de dirección. |
pending_input_count |
PendingInputCount |
Cuántos turnos más recientes se ponen en cola. |
cancel |
Cancellation |
Señal de cancelación cooperativa (cualquier causa). |
cancel_requested |
CancelRequested |
Causa: se solicitó una cancelación explícita. |
timeout_exceeded |
TimeoutExceeded |
Causa: se desencadenó el tiempo de espera por tarea. |
shutdown |
Shutdown |
El contenedor se apaga. |
await ctx.exit_for_recovery() |
await ctx.ExitForRecoveryAsync() |
Aplazar trabajo sin terminar; deja el registro en curso durante una vigencia posterior. |
entry_mode
/
EntryMode valores:
| Value | Meaning |
|---|---|
fresh / Fresh |
Primera ejecución para este (task_id, input_id). |
resumed / Resumed |
Un turno posterior de una cadena existente. |
recovered / Recovered |
Una duración anterior ejecutó este intento y no finalizó; se vuelve a invocar con la entrada persistente. |
TaskRun
Identificador devuelto por start / StartAsync.
Python (TaskRun[Output]) |
C# (TaskRun<T>) |
Descripción |
|---|---|---|
task_id |
TaskId |
La identidad de trabajo. |
input_id |
InputId |
Identidad de entrada. |
metadata |
Metadata |
Referencia de metadatos dinámicos mientras está en curso. |
is_queued |
IsQueued |
True si esta entrada se puso en cola detrás de un giro direccionable activo. |
await run.result() |
await run.GetResultAsync() |
Espere la salida. |
await run.cancel() |
await run.CancelAsync() |
Cancelar de forma cooperativa. |
await run |
run.GetAwaiter() |
Esperable directamente. |
Directiva de reintentos
Los reintentos se aplican a los errores del controlador, no a la recuperación de bloqueos. La recuperación de bloqueos vuelve a escribir el mismo intento y no consume el presupuesto de reintento.
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 retraso: min(initial_delay * backoff_coefficient ** attempt, max_delay).
Estado y excepciones de tareas
TaskStatus (C#) / valores de estado: Pending, InProgress, Suspended, Completed.
| excepción de Python | Excepción de C# | Se genera cuando |
|---|---|---|
TaskConflictError |
TaskConflictException |
Una tarea simultánea no direccionable start golpeó una tarea en vuelo. |
TaskCancelled |
TaskCancelledException |
Se canceló la ejecución. |
TaskFailed |
TaskFailedException |
El controlador produjo un error en el terminal. |
TaskDeferred |
TaskDeferredException |
El trabajo se aplazaba para la recuperación. |
SteeringQueueFull |
SteeringQueueFullException |
La cola de dirección está a capacidad. |
LastInputIdPreconditionFailed |
LastInputIdPreconditionFailedException |
if_last_input_id
/
IfLastInputId no coincidía. |
InputTooLarge |
InputTooLargeException |
La entrada superó el límite de carga de tareas (~10 MiB). |
Habilitación de tareas resistentes
El subsistema de tareas resistentes es opcional. Llame set_resilient_tasks_enabled(True) a antes del inicio del host (normalmente en el momento de la importación), por lo que AgentServerHost crea y TaskManager ejecuta el examen de recuperación de inicio. Sin él, get_task_manager() genera TaskManagerNotInitialized y .run().start() / no puede ejecutar una tarea, declarando o @task@multi_turn_task no habilita el subsistema por sí mismo.
from azure.ai.agentserver.core.tasks import set_resilient_tasks_enabled
set_resilient_tasks_enabled(True) # call at import time, before host startup
Opciones de respuestas resistentes
Se establece en ResponsesServerOptions al construir el host. Ambas marcas están desactivadas de forma predeterminada.
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# | Predeterminado | Descripción |
|---|---|---|---|
resilient_background |
ResilientBackground |
False |
Vuelva a invocar el controlador al reiniciar. Solo se aplica a store=true, background=true respuestas. |
steerable_conversations |
SteerableConversations |
False |
Poner en cola un turno simultáneo en lugar de rechazarlo. |
default_fetch_history_count |
DefaultFetchHistoryCount |
100 |
Número máximo de artículos de historial hidratados por turno. |
sse_keep_alive_interval_seconds |
— | None |
Intervalo de mantenimiento de SSE. |
shutdown_grace_period_seconds |
— | 10 |
Segundos para esperar a que el trabajo en vuelo se apague. |
Compatible con la recuperación ResponseContext
Disponible en el controlador de context respuesta cuando se habilita la resistencia.
| Python | C# | Descripción |
|---|---|---|
context.is_recovery |
IsRecovery |
True cuando se volvió a invocar el controlador después de un bloqueo. |
context.persisted_response |
PersistedResponse |
La última instantánea de respuesta de punto de comprobación duradera. |
context.conversation_chain_metadata |
ConversationChainMetadata |
Pequeñas referencias de cruce y marcas de agua. |
| — | ConversationChainId |
Identidad estable de la cadena de conversación. |
context.is_steered_turn |
IsSteeredTurn |
True si este turno fue promocionado desde la cola de dirección. |
context.pending_input_count |
PendingInputCount |
Las versiones más recientes vuelven a esperar en la cola. |
await context.exit_for_recovery() |
await ExitForRecoveryAsync() |
Aplazar la recuperación durante el apagado; deja la respuesta in_progress. |
Registro de streaming
Elija una copia de seguridad en el inicio y busque secuencias por un identificador 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()
| Configurator | Volver a reproducir | Sobrevive al reinicio |
|---|---|---|
use_in_memory_live() |
No | No |
use_in_memory_replay(*, cursor_fn=None, ttl_seconds=None) |
Sí, dentro de TTL | No |
use_file_backed_replay(*, storage_dir=None, cursor_fn=None, ttl_seconds=None, serializer=None, deserializer=None) |
Sí | Sí |
Operaciones del Registro: await streams.get_or_create(id), await streams.delete(id). Pase cursor_fn para habilitar subscribe(after=...) y last_cursor().
Excepciones de streaming: EventStreamClosedError/EventStreamClosedException,EventStreamNotFoundException/EventStreamNotFoundError y la base .EventStreamError/EventStreamException
Contenido relacionado
- Resistencia para agentes hospedados de larga duración
- Recuperación del trabajo de ejecución prolongada después de un bloqueo
- Dirigir un turno de agente en vuelo
- Transmisión de la salida del agente de ejecución prolongada con reconexión
- Administrar el estado de los agentes de larga duración
- Almacén de estado duradero para agentes hospedados