Funções

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

Seu código de tratamento pode ser executado em um servidor de aplicações, em um processo executor ou em um ambiente que você controla. Associar um ambiente a uma sessão não faz com que as ferramentas de função sejam executadas automaticamente nele.

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

Defina uma função

Adicione uma definição de função a agent.tools ao configurar o agente. Defina 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
  }
}

Processe as ações necessárias

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

Uma entrada de função em required_actions tem este formato:

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 determinar quais chamadas precisam de resultados; um item function_call no histórico da sessão, por si só, não confirma que há um resultado pendente.

Retorne o resultado

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

• Em caso de sucesso, defina success: true e forneça output como uma string ou um array de conteúdo compatível. Serialize objetos JSON em strings.
• Em caso de erro, defina success: false e forneça em error uma mensagem que o agente possa usar.

Para cada chamada pendente de get_customer, execute sua consulta e retorne o resultado. Aqui, 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 o desfecho do turno e recuperar sua saída.

Retome após uma desconexão

Recupere a sessão para encontrar 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, organizados por sessão, turno e ID da chamada. Se a execução pode ter sido bem-sucedida, mas nenhum resultado foi salvo, verifique o desfecho antes de executar a função novamente.

Carregue funções sob demanda

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