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 un appel, 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. Associer un environnement à une session n’y exécute pas automatiquement les outils de type fonction.

Si vous utilisez l’appel de fonction dans l’API Responses, vous pouvez réutiliser votre implémentation de fonction avec le déroulement de session décrit ici.

Définissez une fonction

Ajoutez une définition de fonction à agent.tools lorsque vous configurez l’agent. Donnez-lui un nom, une description et un schéma JSON Schema pour 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
  }
}

Traitez les actions requises

Lorsque l’agent a besoin du résultat d’une fonction, la session émet agent.session.requires_action. Lisez les appels en attente dans event.session.required_actions. Vous pouvez aussi récupérer la session et lire session.required_actions sans diffusion en continu.

Une entrée de fonction dans required_actions se présente ainsi :

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. Utilisez required_actions pour déterminer quels appels nécessitent des résultats ; la seule présence d’un élément function_call dans l’historique de la session ne permet pas d’établir qu’un résultat est attendu.

Renvoyez 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, utilisez success: true et fournissez output sous forme de chaîne de caractères ou de tableau de contenu pris en charge. Sérialisez les objets JSON en chaînes de caractères.
• En cas d’erreur, utilisez success: false et fournissez dans error un message que l’agent peut exploiter.

Pour chaque appel get_customer en attente, effectuez votre recherche et renvoyez son résultat. Ici, 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 après avoir reçu les résultats requis. Suivez les événements et éléments de session pour vérifier l’issue du tour et récupérer sa sortie.

Reprenez après une déconnexion

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

Pour les fonctions ayant des effets de bord, enregistrez les résultats de manière persistante, en les indexant par identifiants de session, de tour et d’appel. Si l’exécution a pu réussir sans qu’un résultat ait été enregistré, vérifiez son issue avant de relancer la fonction.

Chargez les fonctions à la demande

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