Functions

An agent is a collection of functions. When a function is called, the function 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 a description of that argument. When another function calls this function 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 fill them in:

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.

Description

The description is needed only when the function is used as a tool. The description tells the model what the function does and when to call the function.

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, and that value becomes the function's result. Otherwise the error propagates to the caller. The ask and invoke commands 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", "url": "{ 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. Recursion is not available. A loop is the way to repeat work.