Fonctions

Les outils de type fonction permettent à un agent d’appeler le code de votre application. Vous définissez la fonction et ses arguments. L’agent demande l’appel de la fonction, votre code renvoie un résultat, puis le harnais poursuit le tour.

Votre gestionnaire peut s’exécuter sur un serveur d’applications, dans un worker ou dans un environnement que vous contrôlez. Le fait de rattacher un environnement à une session n’y déclenche pas automatiquement l’exécution des outils de type fonction.

Si vous utilisez l’appel de fonction dans l’API Responses, vous pouvez réutiliser le code de votre fonction en suivant les étapes décrites ici pour les sessions.

Définir une fonction

Ajoutez une définition de fonction à agent.tools lorsque vous configurez l’agent. Indiquez son nom, sa description et le schéma JSON de ses arguments :

1234567891011{
  "type": "function",
  "name": "get_customer",
  "description": "Look up a customer by ID.",
  "parameters": {
    "type": "object",
    "properties": { "customer_id": { "type": "string" } },
    "required": ["customer_id"],
    "additionalProperties": false
  }
}

Traiter les actions requises

Lorsque l’agent a besoin du résultat d’une fonction, la session émet l’événement agent.session.requires_action. Consultez la liste des appels en attente dans event.session.required_actions. Vous pouvez aussi récupérer la session et consulter session.required_actions sans utiliser le flux d’événements.

Voici un exemple d’entrée correspondant à un appel de fonction dans required_actions :

1234567{
  "type": "function_call",
  "turn_id": "turn_123",
  "call_id": "call_123",
  "name": "get_customer",
  "arguments": { "customer_id": "123" }
}

Exécutez la fonction indiquée avec les arguments fournis. Consultez required_actions pour savoir quels appels attendent un résultat. La seule présence d’un élément function_call dans l’historique de la session ne suffit pas à déterminer si un résultat est encore attendu.

Renvoyer le résultat

Envoyez agent.session.input.tool_result au point de terminaison des événements de session. Copiez turn_id et call_id depuis l’action en attente :

• En cas de réussite, indiquez success: true et fournissez output sous forme de chaîne de caractères ou de tableau de contenu dans un format pris en charge. Sérialisez les objets JSON en chaînes de caractères.
• En cas d’erreur, indiquez success: false et fournissez dans error un message exploitable par l’agent.

Pour chaque appel get_customer en attente, recherchez le client et renvoyez le résultat. Dans cet exemple, action correspond à l’entrée de required_actions :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16const result = {
  turn_id: action.turn_id,
  call_id: action.call_id,
};
let outcome;

outcome = {
  success: true,
  output: JSON.stringify(getCustomer(action.arguments)),
};

await client.beta.agents.sessions.events.create(sessionId, {
  events: [
    { type: "agent.session.input.tool_result", ...result, ...outcome },
  ],
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14import json

action = action.to_dict()

result = {
    "type": "agent.session.input.tool_result",
    "turn_id": action["turn_id"],
    "call_id": action["call_id"],
}

output = get_customer(action["arguments"])
result.update(success=True, output=json.dumps(output))

client.beta.agents.sessions.events.create(session_id, events=[result])

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24result := openai.AgentSessionInputParamAgentSessionInputToolResult{
	TurnID: action.TurnID,
	CallID: action.CallID,
}

arguments := action.Arguments.(map[string]any)
customerID := arguments["customer_id"].(string)
var customer any
if customerID == "123" {
	customer = map[string]any{"name": "Example Customer", "plan": "pro"}
}
output, err := json.Marshal(map[string]any{"found": customer != nil, "customer": customer})
if err != nil {
	panic(err)
}
result.Success = true
result.Output = openai.AgentFunctionCallOutputParamUnion{OfString: openai.String(string(output))}

err = client.Beta.Agents.Sessions.Events.New(ctx, session.ID, openai.BetaAgentSessionEventNewParams{
	Events: []openai.AgentSessionInputParamUnion{{OfParamAgentSessionInputToolResult: &result}},
})
if err != nil {
	panic(err)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25var json = new JsonMapper();

var result =
    AgentSessionInputParam.AgentSessionInputToolResult.builder()
        .turnId(action.turnId())
        .callId(action.callId());
var arguments = json.valueToTree(action._arguments());

boolean found = arguments.path("customer_id").asText().equals("123");
var output = json.createObjectNode().put("found", found);
if (found)
  output.putObject("customer").put("name", "Example Customer").put("plan", "pro");
else output.putNull("customer");
result.success(true).output(json.writeValueAsString(output));

client
    .beta()
    .agents()
    .sessions()
    .events()
    .create(
        EventCreateParams.builder()
            .sessionId(sessionId)
            .addEvent(result.build())
            .build());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18require "json"

result = {
  type: "agent.session.input.tool_result",
  turn_id: action.turn_id,
  call_id: action.call_id
}
arguments = action.arguments

customer_id = arguments[:customer_id] || arguments["customer_id"]
customer = (customer_id == "123") ? {
  name: "Example Customer",
  plan: "pro"
} : nil
result[:success] = true
result[:output] = JSON.generate(found: !customer.nil?, customer: customer)

client.beta.agents.sessions.events.create(session.id, events: [result])

Le harnais poursuit le tour dès qu’il reçoit les résultats requis. Suivez les événements et les éléments de la session pour vérifier l’issue du tour et récupérer sa sortie.

Taille du résultat

Si l’API rejette le résultat d’un outil en raison de sa taille, ramenez sa taille en dessous de 4 Mio (4 194 304 octets) en laissant une petite marge pour les métadonnées de l’API Agents. Tant que l’appel est en attente, réessayez avec les mêmes valeurs de turn_id et de call_id.

Reprendre après une déconnexion

Récupérez la session pour identifier les actions en attente. Si vous avez déjà exécuté une fonction, envoyez le résultat enregistré avec les mêmes valeurs de turn_id et de call_id.

Pour les fonctions qui ont des effets de bord, enregistrez les résultats dans un stockage persistant en les associant aux identifiants de session, de tour et d’appel. Si la fonction a pu s’exécuter avec succès mais qu’aucun résultat n’a été enregistré, vérifiez l’issue de l’exécution avant de relancer la fonction.

Charger les fonctions à la demande

Par défaut, les fonctions sont chargées d’emblée. Pour différer le chargement d’une fonction, indiquez defer_loading: true dans sa définition et ajoutez { "type": "tool_search" } à agent.tools. Consultez la section Recherche d’outils pour voir un exemple complet.