Functions

A function tool describes a callable operation. Your application executes that operation and sends its result back to the waiting Turn.

Define a function

Include a function definition in agent.tools:

const tools = [{
  type: 'function',
  name: 'lookup_order',
  description: 'Look up an order by its ID.',
  parameters: {
    type: 'object',
    properties: { order_id: { type: 'string' } },
    required: ['order_id'],
    additionalProperties: false,
  },
}];

Tools and MCP server labels must have unique names. The rebyte_ prefix is reserved. Deferred function loading is not supported.

Handle a required action

When the model calls your function, the Session enters requires_action. Retrieve the Session or consume its events. Each function action includes turn_id, call_id, name, and arguments.

Validate the arguments, authenticate the operation for the current user, and execute your application handler. The runtime waits for the result; it does not execute your function implementation itself.

Return the result

After your handler produces order, submit it with the IDs from action:

await client.beta.agents.sessions.events.create(sessionId, {
  'Idempotency-Key': `result-${action.call_id}`,
  events: [{
    type: 'agent.session.input.tool_result',
    turn_id: action.turn_id,
    call_id: action.call_id,
    success: true,
    output: JSON.stringify(order),
  }],
});

To report failure, send success: false and an error string. Image tool results are not supported. Reuse an idempotency key only for an identical result submission.

Functions and MCP

Function tools hand execution to your application. MCP tools execute through the configured MCP connection and produce mcp_call Items instead. They do not require your application to post a function result.