Agent tools

Describe selected views and actions for agent clients.

A view, lookup, or action becomes an agent tool only when you call .setAgentOptions({ description }) on its definition. The agentOptions property returns that configuration. toAgentTool() returns a tool description, or undefined when the definition has no agent options.

import { callout, defineResource } from '@backlit/sdk'
const orders = defineResource('orders', [])
orders
  .view('detail', ['id'], (ctx) =>
    callout(`Order ${ctx.paramValues.id}`)
  )
  .setAgentOptions({
    description: 'Open one order by its identifier.',
  })
orders.view('tools', () =>
  callout(JSON.stringify(orders.toAgentTools()))
)
export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "tools",
    "slots": {
      "content": [
        {
          "kind": "callout",
          "text": "[{\"name\":\"orders_detail\",\"description\":\"Open one order by its identifier.\",\"source\":{\"kind\":\"link\",\"resource\":\"orders\",\"view\":\"detail\"},\"input\":{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\",\"description\":\"The \\\"id\\\" of the record.\"}},\"required\":[\"id\"],\"additionalProperties\":false},\"mutates\":false}]"
        }
      ]
    }
  }
}

resource.toAgentTools() collects opted-in views, lookups, and actions. resource.views() resource.lookups(), and resource.actions() return definitions in registration order. An app host can use app.resourceNames() and app.loadResource(name) to collect tools across resources.

A tool name is resource_name. A view tool has mutates: false and describes a link. An action tool has mutates: true and describes an action. These are data objects. The SDK does not start an agent server or execute model calls. The host must route calls through app.renderView or app.handleAction.

A view tool input contains its address parameters as strings. An action input combines address parameters and schema properties into one object. No address parameter can have the same name as a payload property. The action schema must expose a Standard JSON Schema input converter. A missing converter throws E_AGENT_SCHEMA_WITHOUT_JSON. A name collision throws E_AGENT_PARAM_COLLISION.

Apply authorization in middleware and handlers. Tool descriptions do not grant access. See Request handling.

Lookup tools

A lookup also supports setAgentOptions, agentOptions, and toAgentTool. Its input has a required string query plus its address parameters. It has mutates: false. Route it through app.handleLookup to return records. Set search: true in its agent options to identify the resource search lookup for a host that uses that flag. The tool descriptor itself contains the lookup address, description, input, and mutation flag.