Functions

An agent is a collection of functions. When a function is called, it runs its commands in order. Besides commands, a function may declare arguments, a description and an error handler.

Fields

Field	Type	Description
`description`	dynamic string	Describes this function to the LLM. Needed only when the function is used as a tool.
`args`	object of name → argument object	The function's arguments, with their types and descriptions. Descriptions are needed only for tool calling.
`commands`	command block	The commands this function runs.
`onError`	command block	Commands to run if the function raises an error that no command handled.

Arguments

args maps each argument name to its type and description. When another function calls this one with func, only the names matter: the arguments arrive as local variables, and an argument the caller omits is None. When the function is offered to an LLM as a tool, the model reads the type and description of each argument, so give every argument both:

Field	Type	Default	Description
`description`	string		Description of this argument, which is needed only when used in tool calling. Include all the constraints of this argument here for the LLM.
`required`	boolean	true	Whether the argument is required. This only tells the LLM; an argument that is not passed in is set to None.

An argument name follows the rules for variable names. A reserved name such as result or a Python keyword is refused.

Description

The description tells the model what the function does and when to call it. It is needed only when the function is used as a tool, and validation treats a function with a description as a tool: the rules for tool functions, such as no end, apply to it.

Error handling

When a command raises an error that the command's own onError does not handle, the function's onError block runs instead of the rest of the function. Inside the block, exc holds the exception. The block may return a value, which becomes the function's result. Without a return the function returns nothing, and the caller continues. See Error handling.

A function can fail before any of its commands has run, so its onError block can rely only on the function's arguments and on what the block itself sets. Validation refuses an expression in the block that reads anything else. The ask command cannot be used in error handling.

A tool function with an error handler

"lookupOrder": {
  "description": "Looks up one order by id and returns its status and total.",
  "args": {
    "orderId": { "type": "str", "description": "The order id, such as ORD-1042." }
  },
  "commands": {
    "api": { "profile": "orders", "path": "{ f'/orders/{orderId}' }" },
    "return": "{ {'status': result['status'], 'total': result['total']} }"
  },
  "onError": {
    "log": "{ f'Order lookup failed: {exc}' }",
    "return": "{ {'error': 'order not found'} }"
  }
}

Reentrancy

A function cannot call itself while it is running, directly or through other functions. Repeat work with a loop.