Native actions

Give the agent the ability to run your business actions in the user's context.

≈ 5 min read

Concept

A “native action” is a JavaScript function you expose to Guidia from your page. The agent can describe, plan and trigger it following your app's logic, the same way as if the user clicked it themselves.

Declare an action

javascript

window.guidia = window.guidia || {};
window.guidia.registerAction = window.guidia.registerAction || function (spec) {
  (window.guidia.q = window.guidia.q || []).push(["registerAction", spec]);
};

window.guidia.registerAction({
  name: "create_invoice",
  description: "Create a new invoice for the current customer.",
  parameters: {
    amount: { type: "number", description: "Total amount in EUR" },
    customer_id: { type: "string", description: "Customer ID" }
  },
  requires_confirmation: true,
  handler: async ({ amount, customer_id }) => {
    const res = await fetch("/api/invoices", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ amount, customer_id })
    });
    if (!res.ok) throw new Error("Creation failed");
    return await res.json();
  }
});

Supported fields

name: unique snake_case identifier
description: clear sentence (the agent reads it to decide)
parameters: simplified JSON-Schema for arguments
requires_confirmation: if true, the user must click to confirm
requires_user_token: if true, the server requires a signed user JWT
handler: async function that runs the action and returns a serializable result

For sensitive actions (payment, deletion…), use requires_user_token + a backend-signed JWT. See User auth.

Push dynamic context

When the user navigates, selects a customer, etc., push that context to the agent for sharper answers.

javascript

window.guidia.pushContext({
  page: "invoices/list",
  selected_customer_id: "cust_42",
  filters: { status: "draft" }
});