Chamada programática de ferramentas

A chamada programática de ferramentas permite que um modelo escreva e execute JavaScript para coordenar suas ferramentas. Um programa pode chamar ferramentas em paralelo, usar loops e condições e manter resultados intermediários no ambiente de execução hospedado. Isso é útil quando uma tarefa precisa de uma sequência de chamadas de ferramentas relacionadas ou precisa processar grandes volumes de saída das ferramentas antes de retornar um resultado.

Na API Responses, seu aplicativo decide se a chamada programática de ferramentas está disponível e quais ferramentas elegíveis o modelo pode chamar diretamente, por meio de um programa ou das duas formas. O aplicativo continua executando todas as chamadas de ferramentas sob responsabilidade do cliente. A API de Agentes habilita a chamada programática de ferramentas por padrão e gerencia o loop do agente para você.

Consulte a página do modelo antes de habilitar a chamada programática de ferramentas.

Entenda o ambiente de execução

A OpenAI executa cada programa gerado em um novo ambiente de execução V8 isolado. O ambiente oferece suporte a JavaScript com await no nível superior, mas não disponibiliza Node.js, instalação de pacotes, acesso direto à rede, um sistema de arquivos de uso geral, execução de subprocessos, um console nem estado JavaScript persistente entre execuções de programas. Os programas só podem interagir com sistemas externos por meio das ferramentas habilitadas na requisição e podem emitir saídas com text(...) ou image(...).

Para requisições à API Responses, a chamada programática de ferramentas oferece suporte a fluxos de trabalho com zero retenção de dados (ZDR) sem exigir um contêiner persistente de execução de código. A ZDR precisa estar habilitada para a organização ou o projeto; definir store: false permite a continuação sem estado, mas não habilita a ZDR por si só. A elegibilidade e a retenção dependem da requisição completa, incluindo o modelo, as ferramentas e os serviços de terceiros utilizados; consulte os controles de dados.

Escolha quando usar a chamada programática de ferramentas

Use a chamada programática de ferramentas quando uma etapa tiver um fluxo de controle previsível e o código puder retornar um resultado estruturado menor. Use a chamada direta de ferramentas quando uma única chamada for suficiente, cada resultado exigir uma nova avaliação do modelo ou o trabalho exigir aprovação ou preservação de citações ou artefatos nativos.

Configure a chamada programática de ferramentas

Para a API Responses, adicione a ferramenta hospedada programmatic_tool_calling à requisição. Em seguida, defina allowed_callers em cada ferramenta elegível que o programa pode invocar.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28[
  {
    "type": "function",
    "name": "get_inventory",
    "description": "Return an object with sku (string) and available_units (number).",
    "parameters": {
      "type": "object",
      "properties": {
        "sku": { "type": "string" }
      },
      "required": ["sku"],
      "additionalProperties": false
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "sku": { "type": "string" },
        "available_units": { "type": "number" }
      },
      "required": ["sku", "available_units"],
      "additionalProperties": false
    },
    "allowed_callers": ["programmatic"]
  },
  {
    "type": "programmatic_tool_calling"
  }
]

allowed_callers controla como o modelo pode invocar uma ferramenta:

parameters descreve os argumentos da função. Quando uma função retorna dados estruturados previsíveis, output_schema descreve o objeto JSON codificado na string function_call_output.output dessa função. Defina ambos para que o JavaScript gerado possa usar os campos retornados de forma confiável.

Ferramentas compatíveis

Os seguintes tipos de ferramentas oferecem suporte a allowed_callers: ["programmatic"]:

• function e custom
• mcp
• apply_patch
• shell local e hospedado
• code_interpreter

Para ferramentas MCP, a política require_approval da ferramenta pode pausar o programa até que você aprove a chamada.

Para ferramentas hospedadas pela OpenAI, consulte as orientações de retenção de dados e segurança da ferramenta antes de habilitá-la em um programa.

Combine com a pesquisa de ferramentas

A pesquisa de ferramentas é executada como uma ferramenta de nível superior da Responses API, e não de dentro do JavaScript gerado. Ferramentas de função, personalizadas e MCP com defer_loading: true não estão disponíveis inicialmente para um programa. Depois que o modelo carrega uma ferramenta correspondente, um programa posterior pode invocá-la por meio de tools.* quando o allowed_callers dela inclui "programmatic". Um programa que já está em execução não pode invocar a pesquisa de ferramentas, portanto o modelo precisa carregar as ferramentas com carregamento adiado antes de iniciar um programa que precise delas.

Oriente o roteamento quando os dois modos estiverem disponíveis

Quando seu aplicativo permitir que o modelo chame uma função diretamente ou a partir de um programa, associe cada caminho a uma etapa específica do fluxo de trabalho. Instruções genéricas como "use a chamada programática de ferramentas com eficiência" não deixam claro o limite pretendido. Por exemplo:

<tool_orchestration>
Use Programmatic Tool Calling for [bounded stage] using only [eligible tools].
Run independent calls concurrently when safe. Use only documented tool input
and output fields.

Process and reduce the intermediate results, then emit exactly [program result shape],
including the evidence needed for the final answer.

Stop when [condition] is met. Retry transient failures at most [R] times.
Do not repeat completed calls or perform side-effecting actions. If a required
result is still missing, return a clear structured failure.

Use direct tool calls for [semantic judgment, approval, or final validation].
</tool_orchestration>

Veja um exemplo de como usar este modelo:

<tool_orchestration>
Use Programmatic Tool Calling to compare inventory with demand for sku_123
using only get_inventory and get_demand. Run both calls concurrently. Use
only documented tool input and output fields.

Process and reduce the intermediate results, then emit exactly one JSON object
with sku, available_units, requested_units, and shortage_units, where
shortage_units is max(requested_units - available_units, 0). Include
available_units and requested_units as evidence for the calculation.

Stop when both tool results contain the required fields. Retry transient
failures at most 1 time. Do not repeat completed calls or perform
side-effecting actions. If a required result is still missing, return a clear
structured failure.

Use direct tool calls only for approval before any inventory-changing action.
</tool_orchestration>

Para fluxos de trabalho que precisam dos dois modos, defina um único ponto de transição e evite alternar entre caminhos ou repetir o trabalho. Se houver uma alternativa segura, defina-a uma única vez e limite as novas tentativas.

Entenda os itens de resposta do programa

Cada chamada à API continua retornando o objeto padrão da Responses API. A chamada programática de ferramentas não introduz um envelope de resposta separado. Quando o modelo usa a chamada programática de ferramentas, o array output da resposta pode conter:

• Um item program contendo o JavaScript gerado, um call_id e um fingerprint opaco usado para retomar ou reexecutar o programa.
• Um item function_call criado pelo programa. Ele tem seu próprio call_id, que seu aplicativo usa para retornar o resultado da função. Seu caller.caller_id corresponde ao call_id do programa.
• Um item program_output contendo o resultado final e o status do programa. Seu call_id corresponde ao call_id do programa, e seu status é completed ou incomplete.

Esses são itens separados de nível superior em response.output; o campo caller registra a relação de execução entre eles.

Por exemplo, um programa pode pausar enquanto seu aplicativo executa get_inventory e get_demand:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31[
  {
    "type": "program",
    "id": "prog_123",
    "call_id": "call_prog_123",
    "code": "const [stock, demand] = await Promise.all([tools.get_inventory({ sku: 'sku_123' }), tools.get_demand({ sku: 'sku_123' })]); text(JSON.stringify({ sku: stock.sku, available_units: stock.available_units, requested_units: demand.requested_units, shortage_units: Math.max(demand.requested_units - stock.available_units, 0) }));",
    "fingerprint": "opaque_replay_state"
  },
  {
    "type": "function_call",
    "id": "fc_123",
    "call_id": "call_inventory_123",
    "name": "get_inventory",
    "arguments": "{\"sku\":\"sku_123\"}",
    "caller": {
      "type": "program",
      "caller_id": "call_prog_123"
    }
  },
  {
    "type": "function_call",
    "id": "fc_456",
    "call_id": "call_demand_123",
    "name": "get_demand",
    "arguments": "{\"sku\":\"sku_123\"}",
    "caller": {
      "type": "program",
      "caller_id": "call_prog_123"
    }
  }
]

Estes exemplos mostram apenas os itens relevantes de response.output; eles omitem o objeto padrão Responses que os contém. Depois que seu aplicativo retorna os resultados das funções aninhadas, uma resposta posterior pode conter o item program_output completo:

1
2
3
4
5
6
7{
  "type": "program_output",
  "id": "prog_out_123",
  "call_id": "call_prog_123",
  "result": "{\"sku\":\"sku_123\",\"available_units\":42,\"requested_units\":31,\"shortage_units\":0}",
  "status": "completed"
}

A string JSON em program_output.result segue a estrutura de resultado do programa definida nas suas instruções. O item program_output que a contém segue o contrato da API mostrado acima. Esses contratos são distintos. Um item message final pode chegar junto com a saída do programa ou em uma resposta posterior, então continue até receber essa mensagem.

A OpenAI executa o JavaScript gerado pelo modelo no ambiente de execução hospedado. Seu aplicativo executa as chamadas de função retornadas que são de responsabilidade do cliente; ele não executa o JavaScript gerado.

Retorne o resultado da função como um function_call_output. Copie caller da chamada de função sem alterá-lo. O serviço usa esse valor para retomar o programa correto.

Continue após chamadas de função de responsabilidade do cliente

Um programa pode pausar mais de uma vez ao chegar a ferramentas de responsabilidade do cliente. Continue até que a resposta contenha uma mensagem final do assistente:

1. Envie a solicitação com a ferramenta hospedada e as funções que permitem chamadas programáticas.
2. Execute todas as chamadas de função retornadas que sejam de responsabilidade do cliente.
3. Retorne o resultado de cada função com os valores originais de call_id e caller.
4. Trate uma resposta incompleta antes de continuar.
5. Se a resposta não contiver itens function_call pendentes nem um item message final, continue a partir dessa resposta. Com store: false, reenvie os itens de saída; para uma resposta armazenada, use previous_response_id.
6. Pare quando a resposta contiver um item message final. Leia response.output_text ou o conteúdo de recusa da mensagem.

O exemplo a seguir usa store: false, preserva todos os itens da resposta e retorna o resultado de cada função ao programa:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112import OpenAI from "openai";
import { toResponseInputItems } from "openai/lib/responses/ResponseInputItems";

const client = new OpenAI();

const implementations = {
  get_inventory: async ({ sku }) => ({ sku, available_units: 42 }),
  get_demand: async ({ sku }) => ({ sku, requested_units: 31 }),
};

const tools = [
  {
    type: "function",
    name: "get_inventory",
    description:
      "Return an object with sku (string) and available_units (number).",
    parameters: {
      type: "object",
      properties: { sku: { type: "string" } },
      required: ["sku"],
      additionalProperties: false,
    },
    output_schema: {
      type: "object",
      properties: {
        sku: { type: "string" },
        available_units: { type: "number" },
      },
      required: ["sku", "available_units"],
      additionalProperties: false,
    },
    allowed_callers: ["programmatic"],
    strict: true,
  },
  {
    type: "function",
    name: "get_demand",
    description:
      "Return an object with sku (string) and requested_units (number).",
    parameters: {
      type: "object",
      properties: { sku: { type: "string" } },
      required: ["sku"],
      additionalProperties: false,
    },
    output_schema: {
      type: "object",
      properties: {
        sku: { type: "string" },
        requested_units: { type: "number" },
      },
      required: ["sku", "requested_units"],
      additionalProperties: false,
    },
    allowed_callers: ["programmatic"],
    strict: true,
  },
  { type: "programmatic_tool_calling" },
];

const input = [
  {
    role: "user",
    content: "Compare inventory with demand for sku_123.",
  },
];

while (true) {
  const response = await client.responses.create({
    model: "YOUR_MODEL_ID",
    store: false,
    input,
    tools,
  });

  if (response.status !== "completed") {
    throw new Error(`Response ended with status ${response.status}`);
  }

  // Preserve replayable output, including program and reasoning items.
  input.push(...toResponseInputItems(response.output));

  const calls = response.output.filter((item) => item.type === "function_call");

  if (calls.length === 0) {
    const message = response.output.find((item) => item.type === "message");
    if (message) {
      const refusal = message.content.find((part) => part.type === "refusal");
      console.log(response.output_text || refusal?.refusal || "");
      break;
    }
    continue;
  }

  const outputs = await Promise.all(
    calls.map(async (call) => {
      const run = implementations[call.name];
      if (!run) throw new Error(`Unknown tool: ${call.name}`);

      const result = await run(JSON.parse(call.arguments));
      return {
        type: "function_call_output",
        call_id: call.call_id,
        output: JSON.stringify(result),
        // Preserve caller so the runtime can resume the correct program.
        caller: call.caller,
      };
    })
  );

  input.push(...outputs);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117import json

from openai import OpenAI

client = OpenAI()
model = "gpt-6-astra"


def get_inventory(sku):
    return {"sku": sku, "available_units": 42}


def get_demand(sku):
    return {"sku": sku, "requested_units": 31}


implementations = {
    "get_inventory": get_inventory,
    "get_demand": get_demand,
}

tools = [
    {
        "type": "function",
        "name": "get_inventory",
        "description": "Return an object with sku (string) and available_units (number).",
        "parameters": {
            "type": "object",
            "properties": {"sku": {"type": "string"}},
            "required": ["sku"],
            "additionalProperties": False,
        },
        "output_schema": {
            "type": "object",
            "properties": {
                "sku": {"type": "string"},
                "available_units": {"type": "number"},
            },
            "required": ["sku", "available_units"],
            "additionalProperties": False,
        },
        "allowed_callers": ["programmatic"],
    },
    {
        "type": "function",
        "name": "get_demand",
        "description": "Return an object with sku (string) and requested_units (number).",
        "parameters": {
            "type": "object",
            "properties": {"sku": {"type": "string"}},
            "required": ["sku"],
            "additionalProperties": False,
        },
        "output_schema": {
            "type": "object",
            "properties": {
                "sku": {"type": "string"},
                "requested_units": {"type": "number"},
            },
            "required": ["sku", "requested_units"],
            "additionalProperties": False,
        },
        "allowed_callers": ["programmatic"],
    },
    {"type": "programmatic_tool_calling"},
]

input_items = [
    {
        "role": "user",
        "content": "Compare inventory with demand for sku_123.",
    }
]

while True:
    response = client.responses.create(
        model=model,
        store=False,
        input=input_items,
        tools=tools,
    )

    if response.status != "completed":
        raise RuntimeError(f"Response ended with status {response.status}")

    # Preserve every output item, including program and reasoning items.
    input_items.extend(item.model_dump(exclude_none=True) for item in response.output)

    calls = [item for item in response.output if item.type == "function_call"]
    if not calls:
        message = next(
            (item for item in response.output if item.type == "message"), None
        )
        if message:
            refusal = next(
                (part.refusal for part in message.content if part.type == "refusal"),
                "",
            )
            print(response.output_text or refusal)
            break
        continue

    for call in calls:
        run = implementations.get(call.name)
        if run is None:
            raise ValueError(f"Unknown tool: {call.name}")

        result = run(**json.loads(call.arguments))
        input_items.append(
            {
                "type": "function_call_output",
                "call_id": call.call_id,
                "output": json.dumps(result),
                # Preserve caller so the runtime can resume the correct program.
                "caller": call.caller.model_dump() if call.caller else None,
            }
        )

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179package main

import (
	"context"
	"encoding/json"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

type toolArguments struct {
	SKU string `json:"sku"`
}

func main() {
	client := openai.NewClient()
	input := responses.ResponseInputParam{
		responses.ResponseInputItemParamOfMessage(
			"Compare inventory with demand for sku_123.",
			responses.EasyInputMessageRoleUser,
		),
	}
	tools := []responses.ToolUnionParam{
		functionTool(
			"get_inventory",
			"Return an object with sku (string) and available_units (number).",
			"available_units",
		),
		functionTool(
			"get_demand",
			"Return an object with sku (string) and requested_units (number).",
			"requested_units",
		),
		programmaticTool(),
	}

	for {
		response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
			Model: "gpt-6-astra",
			Store: openai.Bool(false),
			Input: responses.ResponseNewParamsInputUnion{OfInputItemList: input},
			Tools: tools,
		})
		if err != nil {
			panic(err)
		}
		if response.Status != "completed" {
			panic(fmt.Errorf("response ended with status %s", response.Status))
		}

		// Preserve every output item, including program and reasoning items.
		input = append(input, outputAsInput(response.Output)...)

		calls := functionCalls(response.Output)
		if len(calls) == 0 {
			if text, ok := finalMessageText(response); ok {
				fmt.Println(text)
				break
			}
			continue
		}

		for _, call := range calls {
			result, err := runTool(call.Name, call.Arguments)
			if err != nil {
				panic(err)
			}
			output, err := json.Marshal(result)
			if err != nil {
				panic(err)
			}

			toolOutput := responses.ResponseInputItemParamOfFunctionCallOutput(string(output))
			toolOutput.OfFunctionCallOutput.CallID = openai.String(call.CallID)
			caller := call.Caller.AsProgram()
			if caller.CallerID == "" {
				panic("function call is missing its program caller")
			}
			// Preserve caller so the runtime can resume the correct program.
			toolOutput.OfFunctionCallOutput.Caller.OfProgram =
				&responses.ResponseInputItemFunctionCallOutputCallerProgramParam{
					CallerID: caller.CallerID,
				}
			input = append(input, toolOutput)
		}
	}
}

func functionTool(name, description, resultField string) responses.ToolUnionParam {
	parameters := map[string]any{
		"type": "object",
		"properties": map[string]any{
			"sku": map[string]any{"type": "string"},
		},
		"required":             []string{"sku"},
		"additionalProperties": false,
	}
	outputSchema := map[string]any{
		"type": "object",
		"properties": map[string]any{
			"sku":       map[string]any{"type": "string"},
			resultField: map[string]any{"type": "number"},
		},
		"required":             []string{"sku", resultField},
		"additionalProperties": false,
	}
	tool := responses.ToolParamOfFunction(name, parameters, true)
	tool.OfFunction.Description = openai.String(description)
	tool.OfFunction.AllowedCallers = []string{"programmatic"}
	tool.OfFunction.OutputSchema = outputSchema
	return tool
}

func programmaticTool() responses.ToolUnionParam {
	tool := responses.NewToolProgrammaticToolCallingParam()
	return responses.ToolUnionParam{OfProgrammaticToolCalling: &tool}
}

func outputAsInput(
	output []responses.ResponseOutputItemUnion,
) []responses.ResponseInputItemUnionParam {
	input := make([]responses.ResponseInputItemUnionParam, 0, len(output))
	for _, item := range output {
		var converted responses.ResponseInputItemUnion
		if err := json.Unmarshal([]byte(item.RawJSON()), &converted); err != nil {
			panic(err)
		}
		input = append(input, converted.ToParam())
	}
	return input
}

func functionCalls(
	output []responses.ResponseOutputItemUnion,
) []responses.ResponseFunctionToolCall {
	calls := make([]responses.ResponseFunctionToolCall, 0)
	for _, item := range output {
		if item.Type == "function_call" {
			calls = append(calls, item.AsFunctionCall())
		}
	}
	return calls
}

func finalMessageText(response *responses.Response) (string, bool) {
	for _, item := range response.Output {
		if item.Type != "message" {
			continue
		}
		text := response.OutputText()
		if text != "" {
			return text, true
		}
		for _, content := range item.AsMessage().Content {
			if content.Type == "refusal" {
				return content.AsRefusal().Refusal, true
			}
		}
		return "", true
	}
	return "", false
}

func runTool(name, argumentsJSON string) (map[string]any, error) {
	var arguments toolArguments
	if err := json.Unmarshal([]byte(argumentsJSON), &arguments); err != nil {
		return nil, fmt.Errorf("parse %s arguments: %w", name, err)
	}

	switch name {
	case "get_inventory":
		return map[string]any{"sku": arguments.SKU, "available_units": 42}, nil
	case "get_demand":
		return map[string]any{"sku": arguments.SKU, "requested_units": 31}, nil
	default:
		return nil, fmt.Errorf("unknown tool: %s", name)
	}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125require "json"
require "openai"

client = OpenAI::Client.new

def get_inventory(sku:)
  {
    sku: sku,
    available_units: 42
  }
end

def get_demand(sku:)
  {
    sku: sku,
    requested_units: 31
  }
end

implementations = {
  "get_inventory" => method(:get_inventory),
  "get_demand" => method(:get_demand)
}
tools = [
  {
    type: :function,
    name: "get_inventory",
    description: "Return an object with sku (string) and available_units (number).",
    parameters: {
      type: :object,
      properties: { sku: { type: :string } },
      required: ["sku"],
      additionalProperties: false
    },
    output_schema: {
      type: :object,
      properties: {
        sku: { type: :string },
        available_units: { type: :number }
      },
      required: %w[sku available_units],
      additionalProperties: false
    },
    allowed_callers: [:programmatic],
    strict: true
  },
  {
    type: :function,
    name: "get_demand",
    description: "Return an object with sku (string) and requested_units (number).",
    parameters: {
      type: :object,
      properties: { sku: { type: :string } },
      required: ["sku"],
      additionalProperties: false
    },
    output_schema: {
      type: :object,
      properties: {
        sku: { type: :string },
        requested_units: { type: :number }
      },
      required: %w[sku requested_units],
      additionalProperties: false
    },
    allowed_callers: [:programmatic],
    strict: true
  },
  { type: :programmatic_tool_calling }
]
input = [
  {
    role: :user,
    content: "Compare inventory with demand for sku_123."
  }
]

loop do
  response = client.responses.create(
    model: "gpt-6-astra",
    store: false,
    input: input,
    tools: tools
  )
  unless response.status == OpenAI::Responses::ResponseStatus::COMPLETED
    raise "Response ended with status #{response.status}"
  end

  # Preserve every output item, including program and reasoning items.
  input.concat(response.output)
  calls = response.output.grep(OpenAI::Models::Responses::ResponseFunctionToolCall)

  if calls.empty?
    message = response.output.find do |item|
      item.is_a?(OpenAI::Models::Responses::ResponseOutputMessage)
    end
    next unless message.is_a?(OpenAI::Models::Responses::ResponseOutputMessage)

    refusal = message.content.find do |content|
      content.is_a?(OpenAI::Models::Responses::ResponseOutputRefusal)
    end
    text = response.output_text
    if text.empty? &&
       refusal.is_a?(OpenAI::Models::Responses::ResponseOutputRefusal)
      text = refusal.refusal
    end
    puts(text)
    break
  end

  calls.each do |call|
    implementation = implementations.fetch(call.name) do
      raise ArgumentError, "Unknown tool: #{call.name}"
    end
    result = implementation.call(**JSON.parse(call.arguments, symbolize_names: true))
    output = {
      type: :function_call_output,
      call_id: call.call_id,
      output: JSON.generate(result)
    }
    # Preserve caller so the runtime can resume the correct program.
    output[:caller] = call.caller_.to_h if call.caller_
    input << output
  end
end

Ao armazenar respostas, você pode continuar a partir de previous_response_id em vez de reenviar todos os itens das respostas anteriores. Envie os novos itens function_call_output como a próxima entrada. Com store: false, reenvie a sequência completa na ordem, incluindo todos os itens de program, raciocínio, chamada de função, saída de chamada de função e program_output.

Para solicitações sem estado a modelos de raciocínio, reenvie todos os itens de raciocínio retornados. Cada item inclui encrypted_content por padrão. Consulte estado da conversa para conhecer o padrão geral de uso sem estado.

Projete ferramentas para programas

• Retorne dados estruturados e compactos que o JavaScript possa inspecionar sem precisar interpretar texto em prosa.
• Use output_schema para definir os campos e tipos esperados no retorno de cada ferramenta e documente seu comportamento em caso de erro. Se a estrutura de retorno não for conhecida de antemão, mantenha a chamada direta à ferramenta para que o modelo possa inspecionar o resultado.
• Defina a estrutura exata do resultado do programa e as evidências necessárias. Retorne uma indicação de falha clara e estruturada quando o programa não conseguir produzir um resultado válido.
• Torne as chamadas de função idempotentes sempre que possível. Uma nova tentativa ou reexecução não deve repetir um efeito colateral inseguro.
• Verifique os argumentos e as permissões de cada chamada no seu aplicativo, mesmo quando ela vier de um programa hospedado.
• Dê nomes e descrições específicos às ferramentas para que o modelo possa combiná-las corretamente.
• Exija aprovação no nível do aplicativo antes de ações de alto impacto, independentemente de quem fizer a chamada.

Avalie a chamada programática de ferramentas

A chamada programática de ferramentas pode reduzir a quantidade de saídas intermediárias de ferramentas adicionadas ao contexto do modelo, mas o efeito depende da tarefa e das respostas das ferramentas. Comece usando a chamada direta de ferramentas como referência e depois compare as duas abordagens em tarefas representativas.

Defina o nível de qualidade da resposta final e as evidências necessárias antes de medir a eficiência. Avalie o uso de tokens e as chamadas de ferramentas junto com a correção, a completude e a cobertura das evidências, e deixe explícita qualquer concessão de qualidade aceita.

Meça:

• Correção, completude e cobertura das evidências na resposta final.
• Tokens de entrada e totais, latência de ponta a ponta e custo.
• Turnos do modelo, chamadas de ferramentas, novas tentativas e comportamento de recuperação.
• Resultados de segurança, especialmente quanto a efeitos colaterais e requisitos de aprovação.
• Se o caminho executado correspondeu à etapa pretendida do fluxo de trabalho.

API de Agentes

Na API de Agentes, a chamada programática de ferramentas é executada no harness do agente gerenciado pela OpenAI e está habilitada por padrão. O harness fornece ao agente uma ferramenta exec e disponibiliza suas ferramentas existentes no código JavaScript gerado. Você não precisa encapsular essas ferramentas como programas de linha de comando nem instalá-las no sandbox.

Para desabilitar a chamada programática de ferramentas, inclua esta entrada em agent.tools:

1234{
  "type": "programmatic_tool_calling",
  "enabled": false
}

Omitir a entrada ou seu campo enabled mantém a chamada programática de ferramentas habilitada. Uma entrada que contém apenas o tipo, { "type": "programmatic_tool_calling" }, também a mantém habilitada. A configuração de allowed_callers e o loop de continuação da Responses apresentados acima descrevem a integração com a API Responses.

A chamada programática de ferramentas também funciona em sessões somente de conversa com environment.type definido como none. Bash, servidores MCP executores e outras ferramentas que são executadas em um sandbox continuam exigindo um ambiente de execução.

Orquestrar uma ferramenta em JavaScript não muda onde ela é executada. Uma chamada de shell executa comandos no sandbox; o ambiente de execução JavaScript não inicia processos do sistema por conta própria. Os servidores MCP executores continuam usando o sandbox, e as ferramentas de função continuam chamando o servidor do seu aplicativo. O agente processa os resultados dessas ferramentas antes de decidir o que entra no contexto do modelo.

Use as orientações de roteamento acima para definir quais etapas do fluxo de trabalho devem usar código. Siga as instruções em Funções e Conexões MCP para configurar a API de Agentes e tratar as chamadas.

Guias relacionados

• Use a chamada de função para definir funções de responsabilidade do cliente.
• Use a pesquisa de ferramentas para adiar o carregamento de definições extensas de ferramentas até que um modelo precise delas.
• Use o estado da conversa para dar continuidade a solicitações armazenadas ou sem estado da Responses API.
• Consulte os controles de dados antes de escolher um modo de armazenamento.