Skip to main content

​
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/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