Funciones

Las herramientas de función permiten que un agente llame al código de tu aplicación. Tú defines la función y sus argumentos. El agente solicita una llamada, tu código devuelve un resultado y el arnés de ejecución continúa el turno.

Tu manejador puede ejecutarse en un servidor de aplicaciones, un worker o un entorno que controles. Asociar un entorno a una sesión no hace que las herramientas de función se ejecuten automáticamente allí.

Si usas llamadas a funciones en la API Responses, puedes reutilizar la implementación de tu función con el flujo de sesión que se describe aquí.

Define una función

Agrega una definición de función a agent.tools cuando configures el agente. Asígnale un nombre, una descripción y un esquema JSON Schema para sus argumentos:

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
  }
}

Maneja las acciones requeridas

Cuando el agente necesita el resultado de una función, la sesión emite agent.session.requires_action. Lee las llamadas pendientes en event.session.required_actions. También puedes recuperar la sesión y leer session.required_actions sin transmisión continua.

Una entrada de función en required_actions tiene este aspecto:

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

Ejecuta la función indicada con los argumentos proporcionados. Usa required_actions para determinar qué llamadas necesitan resultados; un elemento function_call en el historial de la sesión no basta por sí solo para establecer que hay un resultado pendiente.

Devuelve el resultado

Envía agent.session.input.tool_result al punto de acceso de eventos de la sesión. Copia turn_id y call_id de la acción pendiente:

• Si la ejecución tiene éxito, establece success: true y proporciona output como una cadena o un arreglo de contenido compatible. Serializa los objetos JSON como cadenas.
• Si ocurre un error, establece success: false y proporciona en error un mensaje que el agente pueda usar.

Para cada llamada pendiente a get_customer, realiza tu consulta y devuelve su resultado. Aquí, action es la entrada 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])

El arnés de ejecución continúa el turno después de recibir los resultados requeridos. Sigue los eventos y elementos de la sesión para comprobar el resultado del turno y recuperar su salida.

Recupérate de una desconexión

Recupera la sesión para encontrar las acciones pendientes. Si ya ejecutaste una función, envía su resultado guardado con los mismos valores de turn_id y call_id.

Para las funciones con efectos secundarios, almacena los resultados de forma persistente por sesión, turno e ID de llamada. Si la ejecución pudo haber tenido éxito, pero no se guardó ningún resultado, comprueba qué ocurrió antes de volver a ejecutar la función.

Carga funciones bajo demanda

De forma predeterminada, las funciones se cargan por adelantado. Para diferir la carga de una función, establece defer_loading: true en su definición e incluye { "type": "tool_search" } en agent.tools. Consulta Búsqueda de herramientas para ver un ejemplo completo.