Skip to main content

Function tool

What shipped​

A function you've written can now be attached to an agent as a tool, the same way a workflow is. The agent calls it by name, passes the inputs the function declares, and reads back whatever the function returns. There's no separate tool record to create: the function's description tells the agent when to use it, and its input schema is the tool's inputs.

Who it's for​

Developers who need a small piece of custom logic, such as a calculation, a lookup, or a reshaping of data, that's simpler to write as code than to build as a workflow.

How to use​

  1. Write the function, and give it a description and its inputs. A function with no description isn't offered to agents, because the agent has nothing to decide with.
  2. Attach the function to an agent from the agent's tools.
  3. In a conversation, the agent calls it when the description matches what the user needs.

Calls are checked against the function's inputs before the function runs. A missing required input, a value of the wrong type, or an input the function doesn't declare is refused, and the agent is told why.

What the agent reads back​

The functionThe agent reads
Returns dataThat data, as the tool's result. Turn on Save result to to also keep it in a variable.
Returns nothing, but sent messages"Shown to the user."
Returns nothing and sent nothingThat the function finished and returned no data
Returns haltTurn(result)result, and then its turn ends until the user's next message
FailsThe error message, for example { error: "…" }. See Handle errors.

Functions can also run from an agent's Lifecycle hooks and tool hooks, for example On session start or Before tool call, the same way a workflow does there.

Global variables​

A function reads and writes global variables with variables.global.get([...]) and variables.global.set({...}).

  • They only work when agentic flows (shared memory) are enabled for the agent. Otherwise variables.global.get returns undefined for every name and variables.global.set has no effect. This is intended: functions follow the same rule as workflows.
  • Write variable names as literals, for example variables.global.get(["tier", "locale"]) or variables.global.set({ lastOrderId: id }). The names a function uses are detected when you save it, and only those are sent when it runs. A name held in a variable, as in variables.global.get([name]), isn't detected, so it comes back undefined.
  • Writes are applied only when the function finishes without throwing. If it throws, none of its writes are kept.
  • PR: #5046
  • Related docs: Workflow tool, Agent functions (writing an agent function: tables, APIs, global variables, messages, errors, testing)