Tools

Recipes

How a tool builds its requests and what the agent sees of them.

The recipe tells a tool which requests it sends to the connection, where the values come from, and what the agent gets to see of the response.

Example

{
  "kind": "fetch",
  "announce": true,
  "announce_text": "One moment, I am checking for free slots.",
  "sources": {
    "a": {
      "method": "GET",
      "url": "/slots?date={{date}}",
      "params": [
        {
          "from": "llm",
          "name": "date",
          "value": "The caller's preferred day in the format YYYY-MM-DD",
          "type": "string",
          "required": true
        }
      ]
    }
  },
  "output": {
    "fields": [
      "slots"
    ],
    "limit": 5,
    "remember": []
  }
}

Fields

Field	Meaning
`kind`	`fetch` reads data, `action` triggers something, such as a booking.
`announce`	Whether the agent says something while the tool runs.
`announce_text`	What it says then.
`sources`	The requests, named by letter and run in that order: `a`, `b`, `c`.
`output.fields`	Which fields of the response the agent sees. Everything else stays with you.
`output.limit`	Maximum number of entries when the response is a list. `null` for all.
`output.remember`	Fields the agent keeps for later tools, such as `results.id`.

Request (`sources`)

Field	Meaning
`method`	`GET`, `POST`, `PUT`, `PATCH` or `DELETE`.
`url`	Path relative to the connection's `base_url`. `{{name}}` inserts a parameter.
`for_each_of`	Runs the request once per entry of an earlier request, e.g. `"a"`.
`params`	The parameters, see below.

Parameters (`params`)

Field	Meaning
`from`	`llm`: the agent fills in the value from the conversation. `fixed`: a constant. `variable`: a conversation variable from Get space.
`name`	Parameter name. Dots build nested fields: `address.street`, `items.0.sku`.
`value`	For `llm` the instruction to the agent, for `fixed` the value, for `variable` the variable name.
`type`	`string`, `integer`, `number`, `boolean`, `array` or `object`.
`required`	Whether the parameter must be present.
`fields`	The child fields for `array` and `object`.
`values`	Allowed values, optional.

With GET, parameters that are not placeholders in url go into the query string; with the other methods they go into the JSON body.

Good recipes

With from: llm, say in value exactly what is meant and in which format: "The caller's preferred day in the format YYYY-MM-DD" rather than "date".
Give the agent only what it needs to answer through output.fields. Fewer fields means fewer mistakes.
Check every request first with Send test request.