Funções

As ferramentas de função permitem que um agente chame o código do seu aplicativo. Você define a função e seus argumentos. O agente solicita a chamada, seu código retorna o resultado e o harness dá continuidade ao turno.

O código que processa a chamada pode ser executado em um servidor de aplicação, em um worker ou em um ambiente que você controla. Vincular um ambiente a uma sessão não faz com que as ferramentas de função sejam executadas automaticamente nesse ambiente.

Se você usa a chamada de função na Responses API, pode reutilizar a implementação da sua função no fluxo de sessão descrito aqui.

Definir uma função

Adicione a definição da função a agent.tools ao configurar o agente. Especifique um nome, uma descrição e um JSON Schema para os argumentos da função.

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

Processar as ações necessárias

Quando o agente precisa do resultado de uma função, a sessão emite o evento agent.session.requires_action. Consulte as chamadas pendentes em event.session.required_actions. Você também pode recuperar a sessão e consultar session.required_actions sem usar streaming.

Veja um exemplo de entrada de função em required_actions.

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

Execute a função indicada com os argumentos fornecidos. Use required_actions para identificar quais chamadas aguardam resultados. A presença de um item function_call no histórico da sessão, por si só, não indica que há um resultado pendente.

Retornar o resultado

Envie agent.session.input.tool_result ao endpoint de eventos da sessão. Copie turn_id e call_id da ação pendente.

• Se a execução for bem-sucedida, defina success: true e forneça output como uma string ou um array de conteúdo em um formato compatível. Serialize os objetos JSON como strings.
• Se ocorrer um erro, defina success: false e forneça em error uma mensagem que o agente possa usar.

Para cada chamada pendente de get_customer, consulte os dados do cliente e retorne o resultado. Neste exemplo, action é a 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])

O harness dá continuidade ao turno após receber os resultados necessários. Acompanhe os eventos e itens da sessão para verificar como o turno terminou e recuperar a saída gerada.

Tamanho do resultado

Se a API rejeitar o resultado de uma ferramenta por ser grande demais, reduza o tamanho para menos de 4 MiB (4.194.304 bytes), deixando uma pequena margem para os metadados da Agents API. Enquanto a chamada estiver pendente, tente enviar o resultado novamente com os mesmos valores de turn_id e call_id.

Retomar após uma desconexão

Recupere a sessão para identificar as ações pendentes. Se você já executou uma função, envie o resultado salvo com os mesmos valores de turn_id e call_id.

Para funções com efeitos colaterais, armazene os resultados de forma persistente usando os IDs da sessão, do turno e da chamada. Se houver a possibilidade de a execução ter sido bem-sucedida, mas nenhum resultado tiver sido salvo, verifique o que aconteceu antes de executar a função novamente.

Carregar funções sob demanda

Por padrão, as funções são carregadas de imediato. Para adiar o carregamento de uma função, defina defer_loading: true na definição da função e inclua { "type": "tool_search" } em agent.tools. Consulte Busca de ferramentas para ver um exemplo completo.