Integrate onagent into your app

How the pieces fit together

Four things make up an integration, and they map directly onto the four sections of this page.

1. The onagent CLI — a command-line tool you use to authenticate and manage your apps from a terminal (or a script/CI job) instead of only through the browser console.
2. An app in the console — a namespace (appId) that owns one API key, one allowed origin, one set of tools, and an optional custom system prompt.
3. A tool definition — a YAML file (or the console's tool editor) describing each capability your page exposes: its name, a description the LLM uses to decide when to call it, and a JSON-Schema parameter shape.
4. The browser SDK (@onagent/bridge) — embedded in your page, it opens a WebSocket to the backend, registers your tool handlers, and lets you call bridge.prompt(text) to have the LLM reason about a request and dispatch tool calls back into your page in response.

At runtime: your page calls bridge.prompt("..."), the backend's inference service decides which of your declared tools (if any) to call, the SDK receives that call over the WebSocket, runs the matching handler you registered, and reports the outcome back to the backend.

Get the onagent CLI and log in

onagent is the command-line client for the console API. Everything it does can also be done through the browser console — use whichever fits your workflow. It's the faster path once you're scripting things (CI, bulk tool pushes, etc.).

Install

If you have a Go toolchain available, install straight from the module path:

$ go install github.com/tim72117/onagent/backend/cmd/onagent@latest

This drops an onagent binary in your Go bin directory. No separate download or package registry — the CLI lives in the same repository as the backend it talks to.

Log in

onagent supports two sign-in flows. Both end with a bearer token cached locally (in your per-user config directory), so every later command runs without asking again.

# recommended for interactive use
$ onagent login --web

# headless / no browser available
$ onagent login

Confirm it worked with:

$ onagent list-apps
# a list of apps (even an empty one) means you're logged in.
# "not logged in" means onagent login hasn't succeeded yet.

Full command reference

Every subcommand accepts an optional leading -api <url> flag; omitted below for brevity.

appId values must match ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ — start with a letter or digit, then any mix of letters, digits, -, and _.

Create an app, issue a key, set the allowed origin

These three things can each be done from the CLI or from the console's web UI — pick whichever's convenient; both act on the exact same underlying app record.

$ onagent create-app my-app
Created app "my-app".

Or in the console: sign in at /app and click + New app.

$ onagent issue-key my-app
API key for "my-app" (shown once — copy it now, it can't be retrieved again):
  sk_live_ab12cd34...
Issuing a new key later immediately revokes this one.

$ onagent set-origin my-app https://your-site.example.com
Set "my-app"'s allowed origin to "https://your-site.example.com".

Use the exact origin your page is served from — scheme + host + port, no path, no trailing slash (e.g. https://your-site.example.com, not https://your-site.example.com/ or .../app). In the console UI, the same field is labeled Allowed origin on the app's page.

Define tools and push them

A tool is one capability your page exposes to the LLM: a name it calls, a description that tells the model when to use it, and a JSON-Schema-shaped set of parameters. You can define tools two ways — hand-write a tools.yaml and push it with onagent save-tools, or use the console's built-in tool editor. Both write to the exact same underlying definition; use whichever fits how many tools you have and whether you want them under version control.

tools.yaml schema

Top-level fields:

Each entry under tools:

appId: my-app   # optional — ignored by save-tools; the CLI arg wins
thought: ""    # optional — custom system prompt, or omit for the default
tools:
  - name: search_products
    description: Search the product catalog by keyword.
    parameters:
      type: object
      properties:
        query:
          type: string
          description: The search keywords.
        maxResults:
          type: integer
      required:
        - query
    returns:
      type: array
      items:
        type: object
        properties:
          id: { type: string }
          name: { type: string }
    kind: query   # the LLM needs the actual search results back

  - name: add_to_cart
    description: Add a product to the current user's shopping cart.
    parameters:
      type: object
      properties:
        productId:
          type: string
          description: The product's unique ID.
        quantity:
          type: integer
          description: How many units to add. Defaults to 1 if omitted.
      required:
        - productId
    # kind omitted → defaults to "action"

action vs. query — both block, they differ in what the LLM sees back

The kind field picks between two call flows. As of the current backend, both are blocking — a tool call always holds up the in-flight request until your page responds. The difference is what happens to that response, not whether the platform waits for it.

Push tools

Save the YAML above as tools.yaml and push it:

$ onagent save-tools my-app tools.yaml
Saved 2 tools to "my-app".

onagent validates the file locally before sending anything. The most common validation failures:

• Invalid tool name — doesn't match ^[a-zA-Z_][a-zA-Z0-9_]*$ (no hyphens, no leading digit, no spaces).
• Missing description on a tool.
• Missing parameters.type — the parameters block (or its type field) was omitted entirely.
• Duplicate tool name within the same app.

To read back what's currently saved (e.g. to diff against your local file, or seed a new file from the console editor's state):

$ onagent get-tools my-app > tools.yaml

Setting a custom thought (system prompt)

Beyond individual tool descriptions, an app can carry its own custom instructions for the agent that selects tools — tone, domain rules, anything beyond "call the matching tool":

$ onagent set-thought my-app "Always confirm destructive actions before calling them."
Set "my-app"'s thought.

Pass an empty string to clear it and fall back to the platform default; this can also be embedded as the top-level thought field in tools.yaml.

Embed the SDK and implement tool handlers

@onagent/bridge is the browser-side client: it opens a WebSocket to your onagent backend, registers the tool handlers you provide, and exposes prompt(text) to kick off a request. It buffers calls made before the connection is ready and flushes them once it's open, so you never have to check a "ready" flag yourself.

Install

$ npm install @onagent/bridge

Construct the bridge

import { AgentBridge } from "@onagent/bridge";

const bridge = new AgentBridge({
  url: "wss://onagent.shuttle.tools/ws",
  appId: "my-app",
  apiKey: "YOUR_APP_API_KEY",
  tools: {
    search_products: async ({ query, maxResults }) => {
      const results = await searchCatalog(query, maxResults);
      return results; // kind: query → this value is fed back to the LLM
    },
    add_to_cart: ({ productId, quantity }) => {
      cartStore.add(productId, quantity ?? 1);
      // kind: action (default) → only success/failure reaches the LLM,
      // any returned value here is ignored by the model.
    },
  },
  onAssistantMessage: (text) => showInChat(text),
  onError: (err) => console.error("onagent error", err),
});

Constructor options:

Implement tool handlers

Each key in tools must match a tool name your app has pushed to the platform (via save-tools or the console editor). A handler receives the call's parsed arguments and returns (or resolves to) whatever value is appropriate for that tool's kind:

• For an action tool, the return value is ignored by the LLM — only whether your handler threw determines success/failure. Still return something meaningful if you want it visible via get-tools/codegen tooling, but don't rely on the model seeing it.
• For a query tool, whatever you return (sync or via a resolved Promise) is serialized and fed straight back into the LLM's reasoning — shape it to match the tool's returns schema.
• Throwing (or an async handler's Promise rejecting) reports failure back to the backend with the error's message.

Send a prompt

Once constructed, call bridge.prompt(text) with a natural-language request. That's the entire call — it takes just the text, nothing else:

searchInput.addEventListener("submit", (e) => {
  e.preventDefault();
  bridge.prompt(userInput.value);
});

The LLM reasons about the prompt, picks zero or more of your declared tools, and the SDK dispatches each call to the matching handler automatically. Results and any natural-language reply surface through onAssistantMessage/onError and your handlers' own side effects — there's no separate "context" parameter to pass alongside the prompt text; any state the model needs to reason about should come back to it through a query-kind tool call instead.

Call bridge.close() to tear the connection down permanently — no further reconnect attempts will be made after that.

Using Claude Code? There's a zero-setup skill

If you're integrating onagent from inside Claude Code, the onagent-cli-setup skill (.claude/skills/onagent-cli-setup/) can walk through this entire flow for you — install detection, login, app creation, key issuance, origin setup, and pushing a tools.yaml — using a bundled prebuilt onagent binary, so there's nothing to install manually first. It's a complementary path to everything above, not a replacement: the underlying CLI commands and tools.yaml schema are identical either way, so it's worth reading this page regardless of whether Claude Code drives the mechanics for you.

Troubleshooting

Quick answers to the issues that come up most.