Every tool your agent can act on.

Connector schema

Connectors are defined declaratively. A YAML file describes auth, the base URL, and each action's request and response — including the speakable string the agent reads aloud. The engine can't tell a YAML connector from a hand-coded one.

connector:
  type_key: shopify          # unique identifier
  display_name: Shopify
  category: commerce
  version: "1.0"

auth:
  type: api_key              # api_key | oauth2 | basic | custom
  config_fields:
    - key: shop_domain
      label: Shop Domain
      type: string
      required: true

base_url: "https://{config.shop_domain}/admin/api/2024-01"
default_headers:
  X-Shopify-Access-Token: "{auth.access_token}"

actions:
  lookup_order:
    name: Look Up Order
    supports_realtime: true
    input:
      order_number: { type: string, required: true }
    request:
      method: GET
      path: /orders.json
      query: { name: "{input.order_number}" }
    response:
      root: data.orders[0]
      fields: { order_id: id, status: financial_status }
      speakable: "Order #{order_id} is {status}"
    errors:
      empty_result: "No order found"

Values are interpolated with single-brace {scope.path} syntax (distinct from the workflow engine's {{double braces}}):

Supported auth types:

ToolResult envelope

Every action returns the same standardized shape. The executor usesdata for downstream {{steps.*}}access and speakable for the voice agent.

{
  "success":   true,             // did the action succeed?
  "data":      { ... },          // structured output for {{steps.node.data.*}}
  "speakable": "...",            // natural-language string for the voice agent
  "metadata": {
    "connector":    "shopify",
    "action":       "lookup_order",
    "latency_ms":   860,
    "workspace_id": "ws_..."
  }
}

Build your own connector

1. Create app/connectors/schemas/<type_key>.yaml.
2. Define auth, base_url, and your actions with request and response specs.
3. Restart — the loader scans the directory and registers it automatically.
4. No Python required unless the auth or logic is genuinely custom.

A complete, working connector in ~35 lines:

connector:
  type_key: my_api
  display_name: My API
  category: custom
  version: "1.0"

auth:
  type: api_key
  config_fields:
    - key: api_key
      label: API Key
      type: string
      required: true

base_url: "https://api.example.com/v1"
default_headers:
  Authorization: "Bearer {auth.api_key}"

actions:
  lookup_customer:
    name: Look Up Customer
    supports_realtime: true
    input:
      phone: { type: string, required: true }
    request:
      method: GET
      path: /customers
      query: { phone: "{input.phone}" }
    response:
      root: data.customers[0]
      fields: { name: full_name, status: account_status }
      speakable: "Found {name}, account {status}"
    errors:
      empty_result: "No customer found"