> ## Documentation Index
> Fetch the complete documentation index at: https://docs.widgentic.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Action definition

> The two action kinds, how a template binds them, the execution gates and request limits, and the vocabulary constants — derived from the live validators.

## Kinds

prompt — proposes a message the user reviews and sends from their composer (works with any key); http — a server-side GET/POST to a fixed https URL with an input schema (GET → query, POST → JSON body) and an output schema the response must satisfy; headers/query values may reference the user's secrets by name (\{ "secret": "\<name>" }).

## Binding from a template

* **ACTION** — an element may carry "action": \{ "ref": "\<shared action name>" } or an inline \{ "definition": \{ "kind": "prompt", "text": \["Show the forecast for ", \{ "bind": "city" }] } } / \{ "definition": \{ "kind": "http", "method": "GET", "url": "https\://…", "input": \<schema>, "output": \<schema> } }, plus "input": \{ "\<field>": "\<path>" | \{ "const": \<value> } } and "output": \{ "mode"?: "replace"|"merge"|"patch", "path"?, "map"? }. Bindings resolve at render time; buttons and links (never both href and action) become activatable in Apps hosts. A widget-level "load" (http GET only) runs once when the widget first renders

Put "action": \{ "ref": "\<shared action name>" } or \{ "definition": \<inline definition> } on a button or link (never together with href), plus "input": \{ "\<field>": "\<data path>" | \{ "const": \<value> } } resolved at render time in the element's scope ($root/$parent/\$index available) and "output": \{ "mode": "merge"|"replace"|"patch", "path"?, "map"? }. Arguments must be declared in the action's input schema and must not share a name with a fixed query parameter.

## Execution

http actions run only in Apps hosts that proxy widget tool calls AND under an API key carrying the 'execute' scope (opt-in when the key is created). A render for a read-only key marks them disabled: "scope" (the key lacks execute), "unresolved" (a referenced shared action does not exist). The frame calls execute\_action itself; agents never do. After each http action the widget posts its new payload to the model's context.

## Request limits

http targets must be public https hosts (no private/loopback/link-local, no redirects); the whole request has an 8 s deadline and a 256 KiB response cap; the response must be application/json (or application/\*+json); a 204/empty body arrives as null. Design the output schema for exactly that response.

## Secrets

Secrets are named, write-only, envelope-encrypted, and injected server-side at execution; they never appear in templates, results or logs.

## Vocabulary

| Constant                     | Value                       |
| ---------------------------- | --------------------------- |
| HTTP methods                 | `GET`, `POST`               |
| Output modes                 | `replace`, `merge`, `patch` |
| Maximum resolved prompt text | `2000` characters           |
| Action names                 | `^[a-z][a-z0-9-]{0,63}$`    |
| Secret names                 | `^[a-z][a-z0-9-]{0,63}$`    |