ago-function

name	ago-function
description	Create a client-side function that AGO agents can call from the browser. Generates typed function definitions with JSON schema parameters. Keywords: ago, function, tool, client function, defineFunction, action, browser action.

/ago-function - Create a Client-Side Function

Creates a client-side function that AGO agents can invoke from the user's browser.

Usage

/ago-function <function-name> <description>

Example: /ago-function lookupOrder Look up an order by its ID and display the details

What Are Client Functions?

Client functions are JavaScript/TypeScript functions registered in the browser that AGO agents can call during a conversation. They enable agents to:

• Look up data in the app's state
• Navigate to pages
• Trigger UI actions (open modals, show notifications)
• Read form data or user context

The function runs in the browser, not on AGO's servers.

Steps

1. Ask the user what the function should do

Understand:

• What data/action is needed
• What parameters the agent should provide
• What the function should return
• Where in the app it should be registered

2. Create the function definition

Create a file in the appropriate location (e.g., src/ago-functions/lookupOrder.ts):

import { defineFunction } from "@useago/sdk";

export const lookupOrder = defineFunction({
  name: "lookupOrder",
  description: "Look up an order by its ID and return order details",
  parameters: {
    type: "object",
    properties: {
      orderId: {
        type: "string",
        description: "The order ID to look up",
      },
    },
    required: ["orderId"],
  },
  handler: async (args) => {
    const orderId = args.orderId as string;
    // Implementation here
    const order = await fetchOrder(orderId);
    return {
      id: order.id,
      status: order.status,
      total: order.total,
      items: order.items.length,
    };
  },
});

3. Register the function

Option A: Vanilla JS/TS (register on the client directly)

import { agoClient } from "./lib/ago";
import { lookupOrder } from "./ago-functions/lookupOrder";

agoClient.registerFunction(lookupOrder);

Option B: React (register via hook — auto-cleanup on unmount)

import { useAgoFunction } from "@useago/sdk/react";
import { lookupOrder } from "../ago-functions/lookupOrder";

function OrderPage() {
  useAgoFunction(lookupOrder.name, {
    description: lookupOrder.description,
    parameters: lookupOrder.parameters,
    handler: lookupOrder.handler,
  });

  return <div>...</div>;
}

4. Register navigation (special case)

If the function is about page navigation, use the dedicated helper:

// Vanilla
client.registerNavigationFunction(navigate, [
  { name: "orders", path: "/orders", description: "Orders list page" },
  { name: "order-detail", path: "/orders/:id", description: "Order detail page" },
  { name: "settings", path: "/settings", description: "Settings page" },
]);

// React
import { useAgoNavigation } from "@useago/sdk/react";

useAgoNavigation(navigate, [
  { name: "orders", path: "/orders", description: "Orders list page" },
  { name: "order-detail", path: "/orders/:id", description: "Order detail page" },
]);

Parameter Schema Rules

Parameters follow JSON Schema format:

parameters: {
  type: "object",
  properties: {
    name: { type: "string", description: "Human-readable description for the agent" },
    count: { type: "number", description: "How many items" },
    active: { type: "boolean", description: "Whether to filter active only" },
    status: { type: "string", enum: ["open", "closed", "pending"], description: "Filter by status" },
  },
  required: ["name"],  // Only list truly required params
}

• Always add description to each property — the AI agent reads them to decide what to pass
• Use enum for fixed sets of values
• Keep parameter names simple and descriptive
• The required array should only list parameters the function truly needs

Pre-built Functions

The SDK ships with ready-to-use functions. Register them if needed:

import { showToast, copyToClipboard, openUrl, scrollToElement } from "@useago/sdk";

client.registerFunction(showToast);
client.registerFunction(copyToClipboard);
client.registerFunction(openUrl);
client.registerFunction(scrollToElement);

Available pre-built functions:

• showToast — Show a toast notification
• showNotification — Browser notification
• openUrl — Open a URL in a new tab
• copyToClipboard — Copy text to clipboard
• setTheme — Switch light/dark/system theme
• showConfirmDialog — Show a confirmation dialog
• getUserLocation — Get browser geolocation
• scrollToElement — Scroll to a CSS selector
• setLocalStorage / getLocalStorage — Browser storage
• highlightElement — Highlight a DOM element
• submitForm — Fill and submit a form
• trackEvent — Fire an analytics event

Checklist

After generating:

1. Verify the function has a clear description (the agent reads this)
2. Verify all parameter properties have description
3. Verify the handler returns serializable data (no DOM elements, no circular refs)
4. Verify the function is registered somewhere in the app
5. Run typecheck