Informations de référence sur l’API de l’agent de longue durée

Cette référence répertorie l’aire du Kit de développement logiciel (SDK) AgentServer pour la création d’agents hébergés durables et résilients : les primitives de tâche résilientes, les options réponses résilientes et le registre de diffusion en continu. Pour connaître les concepts de ces API, consultez Résilience pour les agents hébergés de longue durée. Pour obtenir des procédures pas à pas orientées tâches, consultez les guides pratiques.

Packages

Les API de cette page nécessitent au moins les versions de package généralement disponibles suivantes.

Protocole Python (version minimale) .NET (version minimale)
Core (tâches, streaming, stockage) 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
Appels azure-ai-agentserver-invocations ≥ 1.0.0 Azure.AI.AgentServer.Invocations ≥ 1.0.0

Note

Utilisez la dernière version disponible. Les versions répertoriées sont les minimums qui incluent la tâche résiliente, les réponses résilientes et les API de registre de streaming décrites ici.

Tâches résilientes

Les primitives de tâche rendent une unité de travail résiliente aux incidents. Le sous-système de tâche résilient est opt-in : appel set_resilient_tasks_enabled(True) avant le démarrage de l’hôte afin que l’infrastructure construit et TaskManager exécute l’analyse de récupération de démarrage (voir Activer les tâches résilientes).

Déclarer une tâche

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) Travail résilient à un coup. Une entrée produit un résultat.
@multi_turn_task(*, name, title=None, timeout=None, retry=None, steerable=False) Chaîne de conversation qui reste suspended entre les tours. Définissez steerable=True la file d’attente d’un nouveau tour derrière celui actif.

Exécuter une tâche

# 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 Retours Remarques
await task.run(*, input, task_id=None, if_last_input_id=None) Output S’exécute jusqu’à la fin et retourne le résultat.
task.start(*, input, task_id=None, if_last_input_id=None) TaskRun[Output] Retourne un handle que vous pouvez attendre ou annuler.

TaskContext

Le gestionnaire reçoit une TaskContext description de la tentative actuelle.

Python (TaskContext[Input]) C# (TaskContext<T>) Description
input Input Valeur transmise par l’appelant. Conservé avant l’exécution du gestionnaire.
task_id TaskId Identité durable du travail.
input_id InputId Identité par tour/par entrée.
entry_mode EntryMode fresh, resumed, ou recovered.
metadata Metadata Petit état clé-valeur durable (TaskMetadata).
retry_attempt RetryAttempt 0 sur la première tentative.
— RecoveryCount Nombre de récupérations d’incident pour cette tentative.
is_steered_turn IsSteeredTurn True si ce tour a été promu à partir de la file d’attente de direction.
pending_input_count PendingInputCount Nombre de tours plus récents mis en file d’attente.
cancel Cancellation Signal d’annulation coopératif (toute cause).
cancel_requested CancelRequested Cause : une annulation explicite a été demandée.
timeout_exceeded TimeoutExceeded Cause : le délai d’expiration par tâche a été déclenché.
shutdown Shutdown Le conteneur s’arrête.
await ctx.exit_for_recovery() await ctx.ExitForRecoveryAsync() Différer le travail non terminé ; laisse l’enregistrement en cours pour une durée de vie ultérieure.

entry_mode / EntryMode valeurs :

Value Meaning
fresh / Fresh Première exécution pour ce (task_id, input_id).
resumed / Resumed Tour suivant d’une chaîne existante.
recovered / Recovered Une durée de vie précédente a exécuté cette tentative et n’a pas terminé ; réexécrit avec l’entrée persistante.

TaskRun

Handle retourné par start / StartAsync.

Python (TaskRun[Output]) C# (TaskRun<T>) Description
task_id TaskId Identité professionnelle.
input_id InputId Identité d’entrée.
metadata Metadata Informations de référence sur les métadonnées actives pendant la version d’évaluation.
is_queued IsQueued True si cette entrée a été mise en file d’attente derrière un tour orientable actif.
await run.result() await run.GetResultAsync() Attendez la sortie.
await run.cancel() await run.CancelAsync() Annulez coopérativement.
await run run.GetAwaiter() Awaitable directement.

Stratégie de nouvelle tentative

Les nouvelles tentatives s’appliquent aux défaillances du gestionnaire, et non à la récupération en cas d’incident. La récupération d’incident entre à nouveau dans la même tentative et ne consomme pas le budget des nouvelles tentatives.

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

Formule de délai : min(initial_delay * backoff_coefficient ** attempt, max_delay).

État et exceptions des tâches

TaskStatus (C#) / valeurs d’état : Pending, InProgress, Suspended, Completed.

exception Python Exception C# Déclenché quand
TaskConflictError TaskConflictException Une tâche simultanée non orientable start a atteint une tâche en vol.
TaskCancelled TaskCancelledException L’exécution a été annulée.
TaskFailed TaskFailedException Le gestionnaire a échoué terminalement.
TaskDeferred TaskDeferredException Le travail a été différé pour la récupération.
SteeringQueueFull SteeringQueueFullException La file d’attente de direction est en capacité.
LastInputIdPreconditionFailed LastInputIdPreconditionFailedException if_last_input_id / IfLastInputId ne correspond pas.
InputTooLarge InputTooLargeException L’entrée a dépassé la limite de charge utile de la tâche (~10 Mio).

Activer les tâches résilientes

Le sous-système de tâche résilient est opt-in. Appelez set_resilient_tasks_enabled(True) avant le démarrage de l’hôte (généralement au moment de l’importation) afin de AgentServerHost construire et TaskManager d’exécuter l’analyse de récupération de démarrage. Sans cela, get_task_manager() déclenche TaskManagerNotInitialized et .run() / .start() ne peut pas exécuter une tâche, déclarant un @task sous-système ou @multi_turn_task n’active pas lui-même.

from azure.ai.agentserver.core.tasks import set_resilient_tasks_enabled
set_resilient_tasks_enabled(True)   # call at import time, before host startup

Options réponses résilientes

Définissez-le ResponsesServerOptions lors de la construction de l’hôte. Les deux indicateurs sont désactivés par défaut.

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 Appelez à nouveau le gestionnaire lors du redémarrage. S’applique uniquement aux store=trueréponses. background=true
steerable_conversations SteerableConversations False Mettre en file d’attente un tour simultané au lieu de le rejeter.
default_fetch_history_count DefaultFetchHistoryCount 100 Nombre maximal d’éléments d’historique hydratés par tour.
sse_keep_alive_interval_seconds — None Intervalle de maintien en vie de l’SSE.
shutdown_grace_period_seconds — 10 Secondes pour attendre l’arrêt du travail en cours d’exécution.

Prise en compte de la récupération ResponseContext

Disponible sur les gestionnaires de context réponse lorsque la résilience est activée.

Python C# Description
context.is_recovery IsRecovery True lorsque le gestionnaire a été réexécuté après un incident.
context.persisted_response PersistedResponse Dernier instantané de réponse de point de contrôle durable.
context.conversation_chain_metadata ConversationChainMetadata Petites références croisées et filigranes.
— ConversationChainId Identité stable de la chaîne de conversation.
context.is_steered_turn IsSteeredTurn True si ce tour a été promu à partir de la file d’attente de direction.
context.pending_input_count PendingInputCount Les versions plus récentes attendent dans la file d’attente.
await context.exit_for_recovery() await ExitForRecoveryAsync() Différer la récupération lors de l’arrêt ; laisse la réponse in_progress.

Registre de diffusion en continu

Choisissez un stockage au démarrage, puis recherchez les flux par ID par tour.

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()
Configurateur Replay Survivre au redémarrage
use_in_memory_live() Non Non
use_in_memory_replay(*, cursor_fn=None, ttl_seconds=None) Oui, dans la durée de vie Non
use_file_backed_replay(*, storage_dir=None, cursor_fn=None, ttl_seconds=None, serializer=None, deserializer=None) Oui Oui

Opérations de Registre : await streams.get_or_create(id), await streams.delete(id). cursor_fn Passez pour activer subscribe(after=...) et last_cursor().

Exceptions de diffusion en continu : EventStreamClosedError/EventStreamClosedException,EventStreamNotFoundException/EventStreamNotFoundError et la base .EventStreamError/EventStreamException