Approbations et connexions

Comment un programme répond aux demandes d'approbation et de connexion aux connecteurs lors d'un tour : le gestionnaire, la demande qu'il reçoit, les réponses et ce que renvoie turn.answer.

Guide : Approbations.

class ApprovalHandler(Protocol):
    def __call__(
        ctx: ApprovalCallbackContext,
        request: ApprovalRequest,
        /,
    ) -> AllowApproval | DenyApproval | KeepCallbackOpen | Awaitable[AllowApproval | DenyApproval | KeepCallbackOpen]

class ApprovalHandler(Protocol):
    def __call__(
        ctx: ApprovalCallbackContext,
        request: ApprovalRequest,
        /,
    ) -> AllowApproval | DenyApproval | KeepCallbackOpen | Awaitable[AllowApproval | DenyApproval | KeepCallbackOpen]

Une fonction synchrone ou asynchrone de signature (ctx, request) qui répond à une demande d'approbation : AllowApproval, DenyApproval ou KeepCallbackOpen() pour la laisser ouverte. Toute autre valeur de retour, y compris None, lève SdkError. Ses paramètres peuvent porter n'importe quel nom.

• Elle s'exécute dans votre programme et uniquement pendant que agent.run(), session.run() ou turn.result() attend. Entre ces appels, la demande d'approbation reste ouverte. iter_events() ne l'exécute jamais.
• Une fonction synchrone s'exécute sur la boucle d'événements : n'y effectuez aucune opération bloquante. Une fonction async def peut utiliser await.
• Si elle lève une exception ou renvoie une autre valeur, l'appel en attente lève cette erreur et la demande d'approbation reste ouverte. Le tour continue de s'exécuter.
• Elle répond aussi aux demandes d'approbation des sous-agents de la session, avec ctx.session défini sur la session du sous-agent.
• Fondez votre décision sur request.tool.id, l'identifiant stable de l'outil, jamais sur le nom utilisé par le modèle pour l'appeler.
• AllowApproval(scope="session") autorise aussi le même appel avec les mêmes données d'entrée pour le reste de la session.

class ApprovalRequest(
    *,
    tool: ApprovalTool,
    hook: str | None = None,
    title: str,
    input: JsonValue = None,
)

class ApprovalRequest(
    *,
    tool: ApprovalTool,
    hook: str | None = None,
    title: str,
    input: JsonValue = None,
)

Un appel d'outil en attente d'approbation. Les identifiants se trouvent dans le ctx du gestionnaire.

Une demande d'approbation émise par un hook ne peut pas être autorisée pour toute la session. Répondez-y avec AllowApproval(), pour une seule fois.

class ApprovalTool(
    *,
    id: str,
    name: str,
    kind: Literal['builtin', 'client', 'mcp', 'connector', 'plugin'] | UnknownValue,
    description: str | None = None,
    input_schema: dict[str, JsonValue] | None = None,
    output_schema: dict[str, JsonValue] | None = None,
    definition: PythonTool[..., Any] | ClientTool[..., Any] | ToolDefinition | None = None,
    annotations: ToolAnnotations = ToolAnnotations(),
)

class ApprovalTool(
    *,
    id: str,
    name: str,
    kind: Literal['builtin', 'client', 'mcp', 'connector', 'plugin'] | UnknownValue,
    description: str | None = None,
    input_schema: dict[str, JsonValue] | None = None,
    output_schema: dict[str, JsonValue] | None = None,
    definition: PythonTool[..., Any] | ClientTool[..., Any] | ToolDefinition | None = None,
    annotations: ToolAnnotations = ToolAnnotations(),
)

L'outil concerné par une demande d'approbation.

Fondez votre décision sur id, jamais sur name : name varie selon la façon dont le modèle a appelé l'outil. Une indication que l'outil ne déclare pas dans annotations prend la valeur par défaut de MCP, qui retient l'hypothèse la plus défavorable.

class AllowApproval(*, scope: Literal['once', 'session'] = 'once')

class AllowApproval(*, scope: Literal['once', 'session'] = 'once')

Autoriser cet appel une seule fois, ou les appels correspondants pour le reste de la session.

class DenyApproval()

class DenyApproval()

Refuser cet appel.

class KeepCallbackOpen()

class KeepCallbackOpen()

La valeur que renvoie un gestionnaire de callback pour laisser le callback ouvert et permettre à quelqu'un d'y répondre plus tard.

Renvoyez agents.KeepCallbackOpen() depuis on_approval, on_client_tool ou la réponse d'un outil client : rien n'est envoyé, le callback reste ouvert et l'appel en attente renvoie Blocked pour ce callback, sauf si une valeur Blocked qui le liste déjà a été fournie via after= : dans ce cas, l'attente ne se termine qu'à un changement ultérieur. Répondez-y plus tard avec turn.answer, en utilisant AllowApproval ou DenyApproval pour une demande d'approbation et le résultat de l'outil pour un appel d'outil client, ou répondez depuis un autre client.

Cette valeur sert uniquement de retour d'un gestionnaire, jamais de réponse : turn.answer la refuse. None n'a pas non plus cet effet : un gestionnaire d'approbation qui renvoie None lève agents.SdkError, tandis qu'un outil client qui renvoie None envoie le résultat null.

class SignInRequest(
    *,
    source: Literal['connector', 'mcp'] | UnknownValue,
    id: str,
    name: str,
    mode: Literal['connect', 'reconnect'] | UnknownValue = 'connect',
)

class SignInRequest(
    *,
    source: Literal['connector', 'mcp'] | UnknownValue,
    id: str,
    name: str,
    mode: Literal['connect', 'reconnect'] | UnknownValue = 'connect',
)

Une source que la demande de connexion invite l'utilisateur à connecter.

class SignInAnswer(*, connected: Iterable[str] = (), denied: Iterable[str] = ())

class SignInAnswer(*, connected: Iterable[str] = (), denied: Iterable[str] = ())

La réponse à un OpenSignIn : les identifiants des sources que l'utilisateur a connectées et de celles qu'il a refusé de connecter.

Indiquez chaque source demandée dans l'une des listes : une réponse qui en omet une lève SdkError et n'envoie rien, et la demande de connexion reste ouverte. L'agent vérifie chaque source déclarée connectée et reçoit une notification si l'une d'elles ne l'est toujours pas.

class Answered(
    *,
    session_id: str,
    callback_id: str,
    answer: AllowApproval | DenyApproval | None = None,
)

class Answered(
    *,
    session_id: str,
    callback_id: str,
    answer: AllowApproval | DenyApproval | None = None,
)

Le callback était ouvert lors de sa lecture et a reçu une réponse.

class AlreadySettled(*, session_id: str, callback_id: str)

class AlreadySettled(*, session_id: str, callback_id: str)

Une réponse désignait un callback qui n'est plus ouvert : il a reçu une réponse ou a été fermé. Rien n'a changé.

Un autre client peut avoir répondu en premier, le tour du callback peut être terminé, ou la session peut être terminée.

class NotFound(*, session_id: str, callback_id: str)

class NotFound(*, session_id: str, callback_id: str)

Une réponse désignait un callback que la session n'a jamais ouvert et qui n'est ouvert chez aucun de ses sous-agents. Rien n'a changé.

Dès qu'un callback d'un sous-agent n'est plus ouvert, sa session racine renvoie NotFound. La session propre au sous-agent renvoie AlreadySettled.