Referencia de api del agente de ejecución prolongada

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