Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
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