Outils et outils clients

Outils exécutés dans la session, et outils clients dont les appels reçoivent une réponse via un callback.

Guide : Outils.

def agents.tool(
    handler: Callable[..., Any] | None = None,
    /,
    *,
    name: str | None = None,
    namespace: str = 'client',
    description: str | None = None,
    input_schema: type[BaseModel] | None = None,
    output_schema: type[BaseModel] | None = None,
    model_access: ToolModelAccess | None = None,
    annotations: ToolAnnotations | None = None,
    title: str | None = None,
) -> Any

def agents.tool(
    handler: Callable[..., Any] | None = None,
    /,
    *,
    name: str | None = None,
    namespace: str = 'client',
    description: str | None = None,
    input_schema: type[BaseModel] | None = None,
    output_schema: type[BaseModel] | None = None,
    model_access: ToolModelAccess | None = None,
    annotations: ToolAnnotations | None = None,
    title: str | None = None,
) -> Any

Décorez une fonction définie au niveau du module pour en faire un outil du SDK, de type PythonTool.

Utilisez le décorateur seul, @agents.tool, pour reprendre le nom de la fonction, la description de sa docstring, le schéma d'entrée de ses paramètres et le schéma de sortie de son annotation de retour, ou appelez-le pour remplacer l'un de ces éléments. L'outil reste appelable comme la fonction. annotations=agents.ToolAnnotations(read_only_hint=True) déclare des indications incluses dans chaque demande d'approbation d'un appel à l'outil. title="Send email" est un nom destiné aux utilisateurs, par exemple dans une demande d'approbation ; le modèle ne le voit pas.

namespace regroupe l'outil : son identifiant est <namespace>.<name>, ou client.<name> par défaut. Cet identifiant est utilisé par ToolCall.name et les règles d'autorisation, et c'est lui que run_typescript appelle (tools.<namespace>.<name>(...)). Un espace de noms contient des lettres, des chiffres, _ ou $, sans commencer par un chiffre. self, file_system, skill, process, agents, subagent, connectors, guardrail et tout nom commençant par connector_ lèvent SdkError : les outils intégrés de l'agent et les outils de connecteurs et de contrôle du SDK les utilisent. client est l'espace de noms par défaut de chaque outil déclaré par votre code, qu'il s'exécute dans la session ou que ses appels reçoivent une réponse via un callback.

La fonction peut prendre un agents.ToolCallbackContext comme premier paramètre, exclusivement positionnel : def search(ctx: agents.ToolCallbackContext, /, query: str). Le SDK le renseigne à chaque appel.

Lorsque l'agent exécute l'outil, toute exception levée par la fonction est traitée selon Agent(tool_errors=...) : par défaut, le modèle lit The tool failed with an unexpected error., et vos logs reçoivent la trace d'exception. Levez agents.ToolError("...") pour un échec que le modèle doit pouvoir lire. Un appel direct lève l'exception comme le fait la fonction.

class PythonTool[P, R]

class PythonTool[P, R]

Un outil qui exécute une fonction Python là où s'exécute l'agent.

Il est appelable comme la fonction elle-même : tool(...) prend les paramètres de la fonction et renvoie ce qu'elle renvoie, sans rien ajouter. tool_definition décrit l'outil : ce que le modèle voit, et son titre destiné aux utilisateurs.

name reprend par défaut le nom de la fonction, et description sa docstring. Sans input_schema, le schéma d'entrée est construit à partir des paramètres de la fonction, et celle-ci reçoit chaque argument par son nom ; avec ce paramètre, elle reçoit le modèle validé sous la forme args. Le schéma de sortie est construit à partir de l'annotation de retour, sauf si output_schema est fourni. Ces deux paramètres sont des modèles Pydantic. annotations contient les indications de l'outil, comme read_only_hint : chaque demande d'approbation d'un appel à l'outil les inclut dans request.tool.annotations. title est un nom destiné aux utilisateurs, comme "Send email", par exemple dans une demande d'approbation. Un outil ne peut pas être modifié après sa construction.

Une fonction dont le premier paramètre est un agents.ToolCallbackContext exclusivement positionnel reçoit le contexte de chaque appel. Lors d'un appel direct, cet outil accepte que le contexte soit fourni ou omis : search(ctx, "q") et search("q") fonctionnent tous deux, le second utilisant ToolCallbackContext.local().

Chaque champ de tool_definition est aussi accessible sur l'outil : tool.name correspond à tool.tool_definition.name, et tool.input_schema est le schéma JSON Schema, pas la classe Pydantic.

async def invoke(context: ToolCallbackContext | None = None, /, **kwargs: Any) -> Any

async def invoke(context: ToolCallbackContext | None = None, /, **kwargs: Any) -> Any

Appelez l'outil avec les arguments du modèle, comme le fait l'agent.

context est transmis à une fonction qui prend un ToolCallbackContext. Sans ce paramètre, la fonction reçoit ToolCallbackContext.local(). Un outil dont la fonction ne prend pas de contexte l'ignore. Un outil qui déclare des entrées de session prend aussi leurs valeurs sous la forme injected_session_inputs={input_id: value}, et lève ValueError si ce paramètre est absent.

class ToolDefinition(
    *,
    name: str,
    title: str | None = None,
    description: str = '',
    input_schema: dict[str, JsonValue] = {'type': 'object', 'properties': {}},
    output_schema: dict[str, JsonValue] | None = None,
    annotations: ToolAnnotations = ToolAnnotations(),
    source: str | None = None,
    icons: list[dict[str, JsonValue]] | None = None,
    meta: dict[str, JsonValue] | None = None,
    execution: dict[str, JsonValue] | None = None,
)

class ToolDefinition(
    *,
    name: str,
    title: str | None = None,
    description: str = '',
    input_schema: dict[str, JsonValue] = {'type': 'object', 'properties': {}},
    output_schema: dict[str, JsonValue] | None = None,
    annotations: ToolAnnotations = ToolAnnotations(),
    source: str | None = None,
    icons: list[dict[str, JsonValue]] | None = None,
    meta: dict[str, JsonValue] | None = None,
    execution: dict[str, JsonValue] | None = None,
)

La description d'un outil : ce que le modèle en voit (nom, description, schéma d'entrée) et ce qu'une politique peut en lire (titre, annotations, source).

Cet objet décrit tout outil, qu'il soit exécuté par votre fonction Python (un PythonTool en contient un), par un connecteur ou par un serveur MCP. Ses champs sont les champs Tool du Model Context Protocol (MCP), en snake case, auxquels s'ajoute source.

class ToolAnnotations(
    *,
    read_only_hint: bool = False,
    destructive_hint: bool = True,
    idempotent_hint: bool = False,
    open_world_hint: bool = True,
)

class ToolAnnotations(
    *,
    read_only_hint: bool = False,
    destructive_hint: bool = True,
    idempotent_hint: bool = False,
    open_world_hint: bool = True,
)

Indications sur le comportement d'un outil, telles que les définit le Model Context Protocol (MCP), avec les noms MCP comme alias : readOnlyHint pour read_only_hint.

Une indication non déclarée par l'outil prend la valeur par défaut de MCP, qui suppose le pire : l'outil écrit, peut détruire des données, ne peut pas être répété sans risque et accède à des systèmes extérieurs à ceux de l'agent. Une politique qui ne se fie qu'aux indications déclarées refuse donc un outil qui n'en déclare aucune. Il s'agit d'indications : ne vous y fiez que pour les outils provenant de sources de confiance.

class ToolResult[T](
    *,
    content: Sequence[ContentBlock | mcp.types.ContentBlock | Mapping[str, Any]] = [],
    structured_content: object = None,
    is_error: bool = False,
    meta: Mapping[str, JsonValue] = {},
)

class ToolResult[T](
    *,
    content: Sequence[ContentBlock | mcp.types.ContentBlock | Mapping[str, Any]] = [],
    structured_content: object = None,
    is_error: bool = False,
    meta: Mapping[str, JsonValue] = {},
)

Ce qu'un outil renvoie : du contenu pour le modèle, une sortie structurée et des métadonnées pour le client.

Un outil annoté -> ToolResult[T] utilise le schéma JSON Schema de T comme schéma de sortie. ToolResult[T] ne type pas structured_content : le schéma de sortie de l'outil le vérifie lorsque l'outil renvoie son résultat.

@classmethod
def error(
    message: str,
    *,
    structured_content: JsonValue | BaseModel = None,
    meta: Mapping[str, JsonValue] | None = None,
) -> Self

@classmethod
def error(
    message: str,
    *,
    structured_content: JsonValue | BaseModel = None,
    meta: Mapping[str, JsonValue] | None = None,
) -> Self

Une erreur d'exécution de l'outil que le modèle voit sous la forme message et à laquelle il peut réagir.

class ToolError(Exception)

class ToolError(Exception)

Faire échouer l'appel d'outil avec un message que le modèle voit tel quel.

Levez cette exception dans un outil, dans la fonction de réponse d'un outil client ou dans on_client_tool. Le modèle reçoit un appel en échec avec uniquement message, quelle que soit la configuration de Agent(tool_errors=...), et peut réagir, par exemple en interrogeant l'utilisateur ou en rappelant l'outil avec d'autres arguments. structured_content et meta accompagnent le résultat en échec comme avec ToolResult ; le modèle ne voit jamais meta. Renvoyer ToolResult.error(message) à la place produit le même effet. Les deux vérifient structured_content et meta au moment de leur création : une valeur non JSON lève pydantic.ValidationError à cet endroit, dans votre code.

type ToolModelAccess = Literal['direct', 'programmatic', 'both']

type ToolModelAccess = Literal['direct', 'programmatic', 'both']

Mode d'appel d'un outil par le modèle : "programmatic" depuis run_typescript, "direct" depuis sa liste d'outils, ou "both".

Avec "programmatic", le modèle appelle l'outil depuis le code qu'il écrit, sous la forme tools.<namespace>.<name>(...). Il peut ainsi enchaîner plusieurs appels en une étape et parcourir leurs résultats dans une boucle. "direct" convient à un outil que le modèle appelle une fois par tour.

def agents.client_tool(
    function: Callable[..., Any] | None = None,
    /,
    *,
    name: str | None = None,
    namespace: str = 'client',
    description: str | None = None,
    input_schema: type[BaseModel] | None = None,
    output_schema: type[BaseModel] | None = None,
    model_access: ToolModelAccess | None = None,
    annotations: ToolAnnotations | None = None,
    title: str | None = None,
) -> Any

def agents.client_tool(
    function: Callable[..., Any] | None = None,
    /,
    *,
    name: str | None = None,
    namespace: str = 'client',
    description: str | None = None,
    input_schema: type[BaseModel] | None = None,
    output_schema: type[BaseModel] | None = None,
    model_access: ToolModelAccess | None = None,
    annotations: ToolAnnotations | None = None,
    title: str | None = None,
) -> Any

Déclarer un outil que le modèle peut appeler et dont la réponse est fournie par un callback, et non au sein de la session.

Appliquez @agents.client_tool à une fonction de déclaration dont le corps est raise NotImplementedError : le nom provient de la fonction, la description de sa docstring, le schéma d'entrée de ses paramètres et le schéma de sortie de son annotation de retour. Utilisez name= ou description= pour remplacer le nom ou la description. La fonction n'est jamais exécutée : elle décrit uniquement l'outil, et sa fonction de réponse prend les mêmes paramètres. Une fonction de déclaration qui prend un agents.ToolCallbackContext ou une entrée de session lève SdkError. Récupérez le contexte dans la fonction de réponse et lisez les entrées de session dans votre application.

Vous pouvez aussi déclarer l'outil sans fonction, par exemple à partir d'un contrat JSON : passez name=, description=, ainsi que input_schema= et output_schema= sous forme de modèles Pydantic. La fonction de réponse reçoit alors le modèle validé. Sans output_schema=, le modèle ne reçoit aucun schéma de sortie et la valeur de retour de la fonction de réponse n'est pas typée ; le SDK émet donc un UserWarning.

namespace définit le groupe de l'outil : son identifiant est <namespace>.<name>, ou client.<name> par défaut, tel que le renvoient ClientToolCall.name et ToolCall.name. Un espace de noms contient des lettres, des chiffres, _ ou $, et ne commence pas par un chiffre. self, file_system, skill, process, agents, subagent, connectors, guardrail et tout nom commençant par connector_ lèvent SdkError : ils sont réservés aux outils intégrés de l'agent et aux outils de connecteurs et de contrôle du SDK. client est l'espace de noms par défaut de chaque outil déclaré dans votre code, qu'il s'exécute au sein de la session ou reçoive sa réponse par un callback.

annotations contient les indications sur l'outil, que chaque demande d'approbation d'un appel à cet outil inclut dans request.tool.annotations. title est un nom destiné aux utilisateurs, par exemple dans une demande d'approbation.

Un outil client reçoit sa réponse via un callback, et non au sein de la session : le tour attend cette réponse. Répondez-lui avec une fonction liée par @<tool>.answer, ou manuellement avec turn.answer(callback.id, result) lorsqu'un run renvoie Blocked.

class ClientTool[P, R]

class ClientTool[P, R]

Un outil que le modèle peut appeler et dont la réponse est fournie par un callback, et non au sein de la session.

L'agent ne contient que sa déclaration : aucun code ne s'exécute pour lui là où l'agent s'exécute. Quand le modèle l'appelle, le tour attend la réponse au callback. Liez la fonction qui lui répond avec @<tool>.answer, et passez cette fonction à Agent.run via on_client_tool=agents.ClientToolAnswers(...).

Construire un outil avec @agents.client_tool sur une fonction de déclaration, ou avec agents.client_tool(name=..., description=..., input_schema=...).

def answer(handler: Callable[..., Any], /) -> ClientToolAnswer[P, R]

def answer(handler: Callable[..., Any], /) -> ClientToolAnswer[P, R]

Associer la fonction qui répond aux appels de cet outil, dans le processus qui exécute l'agent.

Elle prend les paramètres de l'outil et renvoie son résultat, de façon synchrone ou asynchrone : une valeur du type de retour de la fonction de déclaration, ou un agents.ToolResult pour choisir ce que voit le modèle. Elle renvoie agents.KeepCallbackOpen() pour laisser l'appel ouvert : rien n'est envoyé, et une exécution renvoie Blocked sur cet appel, auquel turn.answer ou un autre client répond. Passez la fonction ainsi associée à Agent.run dans on_client_tool=agents.ClientToolAnswers(...). Elle peut prendre un agents.ToolCallbackContext en premier paramètre, uniquement positionnel, comme un outil : def answer(ctx: agents.ToolCallbackContext, /, city: str). Elle y récupère la session et l'identifiant de l'appel ; sa sandbox n'est pas liée. Ses autres paramètres ne sont pas vérifiés à ce stade. Une fonction de réponse dont les noms ou les catégories de paramètres ne correspondent pas échoue dès son premier appel, sous la forme d'un appel d'outil en échec visible par le modèle. Une fonction de réponse qui utilise seulement un type différent pour un paramètre est tout de même appelée, avec la valeur validée par la déclaration.

def called(callback: OpenCallback, /) -> TypeIs[OpenClientToolCall[P, R]]

def called(callback: OpenCallback, /) -> TypeIs[OpenClientToolCall[P, R]]

Indique si callback est un appel ouvert de cet outil : un OpenClientToolCall dont call.name est l'identifiant de cet outil, <namespace>.<name>.

Un vérificateur de types utilise alors cette fonction de déclaration pour typer callback.run(fn) : fn prend les paramètres de la fonction de déclaration et renvoie son type de retour :

for callback in state.callbacks:
    if get_location.called(callback):
        await turn.answer(callback.id, await callback.run(read_gps))

for callback in state.callbacks:
    if get_location.called(callback):
        await turn.answer(callback.id, await callback.run(read_gps))

class ClientToolAnswer[P, R]

class ClientToolAnswer[P, R]

La fonction qui répond aux appels d'un outil client, associée avec @<tool>.answer.

class ClientToolAnswers(
    *answers: ClientToolAnswer[..., Any],
    default: Callable[[ClientToolCall], Any] | None = None,
)

class ClientToolAnswers(
    *answers: ClientToolAnswer[..., Any],
    default: Callable[[ClientToolCall], Any] | None = None,
)

Vos fonctions de réponse aux outils clients, une par outil, et une fonction par défaut pour tous les autres appels.

Passez cet objet via on_client_tool= à agent.run, agent.start_session ou agent.session(id) :

answers = agents.ClientToolAnswers(get_location.answer(read_gps), default=handle)
state = await agent.run("Find a shop near me", on_client_tool=answers)

answers = agents.ClientToolAnswers(get_location.answer(read_gps), default=handle)
state = await agent.run("Find a shop near me", on_client_tool=answers)

Chaque fonction de réponse provient de <tool>.answer(function), qu'un vérificateur de types compare à la fonction de déclaration de l'outil. default reçoit les appels de tous les autres outils clients, comme un simple gestionnaire on_client_tool= : la fonction de réponse propre à un outil est prioritaire.

Une fonction classique s'exécute dans un thread distinct, pour qu'un appel bloquant comme input() n'interrompe pas la session. Une fonction async def s'exécute sur la boucle d'événements : n'y effectuez aucun appel bloquant. Les fonctions de réponse reçoivent aussi les appels d'outils clients des sous-agents de la session.

Lève SdkError à ce stade si deux fonctions de réponse concernent le même outil. Avant le démarrage de la session, l'agent lève SdkError pour une fonction de réponse associée à une déclaration qui ne fait pas partie de ses outils ou de ceux de ses sous-agents. Un agent déployé chargé avec Agent.load_from ignore cette vérification : il ne possède aucun objet outil.

class ClientToolCall(name: str, arguments: JsonValue)

class ClientToolCall(name: str, arguments: JsonValue)

Un appel d'outil client, tel que le reçoit on_client_tool et que le contient OpenClientToolCall.call.

name est l'identifiant de l'outil : son espace de noms suivi du nom utilisé lors de sa déclaration, par exemple client.get_weather (client est l'espace de noms par défaut) ou ui.get_location. Il correspond à agents.ToolCall.name dans Completed.tool_calls. arguments contient les arguments de l'appel, non validés : ceux du modèle ou ceux définis par un hook pre_tool_call. Le gestionnaire les vérifie.

Un outil qui possède sa propre fonction de réponse dans agents.ClientToolAnswers ne passe jamais par le gestionnaire par défaut : sa fonction de réponse est prioritaire.