Flow Functions

Flow functions let the LLM call your backend during a conversation. You define the HTTP request shape once, attach the function to one or more agents, and the bot executes it server-side when the LLM decides to invoke it.

Use cases: look up an order, check availability, create a ticket, verify a customer — anything where the conversation needs live data or needs to cause a side effect in your system.

Function types

Agent nodes accept two function types, discriminated by the type field:

builtin is the default when type is omitted. http_request requires config.functionId to point at an active flow function in the same account.

Request shape

A flow function describes a structured HTTP request with three independent parameter locations: path, query, and body.

{
  "name": "create_order",
  "description": "Create a new customer order",
  "request": {
    "method": "POST",
    "url": "https://api.example.com/customers/{customerId}/orders",
    "pathParams":  { "type": "object", "properties": { "customerId": { "type": "string" } }, "required": ["customerId"] },
    "queryParams": { "type": "object", "properties": { "source": { "type": "string", "enum": ["phone", "web"] } } },
    "body":        { "type": "object", "properties": { "sku": { "type": "string" }, "quantity": { "type": "integer" } }, "required": ["sku", "quantity"] }
  },
  "paramBindings": {
    "customerId": { "source": "call_context", "contextKey": "caller.contact_id", "onNull": "reject" },
    "source":     { "source": "static", "value": "phone" }
  },
  "webhookHeaders": { "Authorization": "Bearer ..." },
  "timeoutMs": 5000
}

Method and URL

Parameter locations

Each location (pathParams, queryParams, body) is an independent JSON Schema object. Parameter names must be unique across all three — customerId cannot appear in both pathParams and body.

Path and query parameters are restricted to primitives because they flatten into URL strings. Body supports nested structures up to depth 5 to match OpenAI Structured Outputs.

Validation keywords like format, minimum/maximum, pattern, minLength/maxLength pass through to JSON Schema enforcement at dispatch time.

Parameter bindings

paramBindings controls where each parameter's value comes from. Keys match property names at the top of pathParams, queryParams, or body. Dotted paths (body.customer.id) are not supported — bind the whole top-level object instead.

onNull behavior

When a call_context binding resolves to null:

Visibility rules

• Parameters bound to call_context or static are stripped from the LLM's tool schema. The model never sees them.
• Parameters with no binding or { "source": "llm" } appear in the LLM's tool schema and are extracted from conversation.
• At dispatch, the bot merges LLM arguments with context/static values and splits them back into pathParams / queryParams / body buckets.

Headers and timeout

Execution model

Flow functions run server-side:

1. At publish time, the backend resolves every http_request reference to its current function definition. static and call_context bindings are stripped from the LLM schema.
2. Per call, any call_context values are resolved from the live call state. If onNull: reject trips, the function is removed from the tool list for that call.
3. When the LLM invokes the function, the bot publishes a NATS request to the function executor. The executor injects static / call_context values, templates URL placeholders, sends the HTTP request, and returns the response to the bot.
4. The bot feeds the result back to the LLM as the tool result.

Transitions and failure

If the function definition includes transitionTo, the agent transitions to the target node regardless of whether the HTTP call succeeded. On failure the LLM receives the error as the tool result and can reference it from the new node's context. This makes functions usable as deterministic handoff triggers even when the downstream service is flaky.

Attaching to an agent

Add the function to an agent's functions array using type: "http_request" and reference the function ID:

{
  "type": "http_request",
  "name": "create_order",
  "description": "Create a new customer order",
  "config": { "functionId": "550e8400-e29b-41d4-a716-446655440000" },
  "transitionTo": "ConfirmationAgent"
}

The agent's LLM decides when to invoke the function based on the description and the JSON-Schema-derived tool signature. Multiple agents can reference the same function.

Validation

The backend rejects http_request function references at publish time with these error codes:

Request-shape validation at flow-function create/update time includes: method allowlist, unique parameter names across locations, URL placeholders matching pathParams, JSON Schema type/location constraints, and timeout range.