BuilderIO/agent-native / community-templates/outbound-in-your-voice/.agents/skills/actions
actions
VerifiedHow to create and run agent actions. Actions are the single source of truth for app operations — the agent calls them as tools and frontend code calls them through client hooks. Use when creating a new action, adding an API integration, or wiring up frontend data fetching.
Agent Actions
Rule
Actions in actions/ are the single source of truth for app operations. The agent calls them as tools, the frontend calls them through useActionQuery / useActionMutation, and the framework owns the HTTP transport behind those hooks — no duplicate /api/ routes.
Before creating any custom route for app data, check actions/ and the action table in AGENTS.md. An action already exists? Call it directly. Missing? Create or update a defineAction. Stop trigger: about to add a file under server/routes/api/ (or middleware to guard one)? Check it against the exception list in Custom /api/ Routes below first — even if you already started the route.
Keep Actions Deterministic
An action may call a provider API, validate data, and persist records without being an AI feature — keep it deterministic, focused, and independently useful to the agent. Don't put LLM calls or a second model runtime in app actions.
The sanctioned model-backed exception is @agent-native/core/decisions for capability-aware classification and scoring, and it returns a result without performing or authorizing the selected action.
When a workflow is research, analysis, generation, recommendation, or synthesis — or spans several provider calls and writes — route it to the AgentSidebar via sendToAgentChat({ openSidebar: true }) and let the agent orchestrate focused actions instead of hiding an AI-shaped workflow behind one opaque generate-*/create-* action just because its implementation happens to be deterministic.
How to Create an Action
One action per file, default-exported. The filename is the action name (kebab-case): actions/list-meals.ts is the list-meals action. Don't put several defineActions as named exports in one file — the registry keys actions by filename and only the default export is registered, so extra named exports never become callable and won't match .generated/action-types.d.ts.
// actions/list-meals.ts
import { z } from "zod";
import { defineAction } from "@agent-native/core/action";
import { getDb } from "../server/db/index.js";
import { meals } from "../server/db/schema.js";
export default defineAction({
description: "List all meals",
schema: z.object({}),
http: { method: "GET" },
run: async () => {
const db = getDb();
const rows = await db.select().from(meals);
return rows; // Return objects/arrays, NOT JSON.stringify()
},
});
schema (Zod or Standard Schema-compatible) gives runtime validation, TS inference for run() args, and an auto-generated JSON Schema for the tool. Write it so an agent can call the tool correctly on the first try: .describe() every param and state enum values and the default in that text (z.enum(["open","closed"]).default("open").describe('Filter status: "open" or "closed"; defaults to "open"')); mark a field .optional() only when the action truly tolerates its absence — a silent default the caller cannot see is a required field in disguise; name the primary id the same way across a family (create-/get-/update-/delete-<thing> all take id, not a mix of id and <thing>Id), and if one action must differ, accept both with .or(); give nested objects a real schema, never a prose description; keep the one-line description complete enough to call the tool without a second lookup, because compact catalogs and tool-search show only that line. Use z.coerce.number() for numeric HTTP params, but write an explicit boolean parser instead of z.coerce.boolean(), which treats "false" as truthy.
Some models (GPT-6 Luna in strict mode) send every optional field they aren't using, filled with null, [], false, or an enum's only value, so a call must mean the same with that padding as without it. Make an optional switch act only when true (fixedCanvas: true, not responsive: false), and never give [] a meaning of its own such as "none".
Use Drizzle's PostgreSQL query builder, not raw SQL/getDbExec() or direct driver imports, unless Drizzle can't express the query. Never hardcode API keys/tokens/secrets - read via readAppSecret / resolveCredential / OAuth helpers; process.env is deploy-level config only.
Decision order: existing action → extend/create a defineAction → custom route as last resort (Custom /api/ Routes below). Actions are already callable by agents, CLIs, hooks, HTTP, and MCP/A2A — don't wrap them in an umbrella REST API.
Keep the Action Surface Small and Orthogonal
Every agent-exposed action is a tool in the model's context window; more tools degrades tool-selection quality. Add the fewest, most orthogonal actions that cover the capability.
- One orthogonal
updateper resource, not one per field —update-<thing>taking an optional-fields patch, notupdate-<thing>-name+update-<thing>-order+ … - Reach for a generic escape hatch before minting a new read action — the
provider-api-catalog/docs/requesttrio for provider data (references/provider-apis.md),db-queryfor ad hoc app-data reads in dev. agentTool: falsehides a UI-only/programmatic action from the model while keeping it frontend/HTTP-callable — nottoolCallable: false, which only blocks the sandboxed extension bridge and leaves the action visible everywhere else; reserve that one for high-blast-radius operations.- Delete or hide stale actions once you confirm neither the UI nor an agent workflow uses them.
Key Actions — One Index, Every Surface
Document the app's primary actions in the AGENTS.md action table. For first-turn loading, add those action names to the plugin's initialToolNames (INITIAL_TOOL_NAMES in some templates), or mark the full starter set deferLoading: false on the actions. When one action opts into per-action eager loading, unmarked actions are deferred; the remaining actions stay discoverable through tool-search. When users name an action's job in words its name and description lack ("auto-archive rule", "canned reply"), add those words as searchHints: tool-search ranks them just below the name and never shows them to the model.
When MCP is enabled, its Key tools line is generated from mcp.keyToolNames ?? initialToolNames and filtered to the actions served on that surface. A configured mcp.keyToolNames overrides the advertised MCP/WebMCP key list; it does not change the in-app agent's first-turn list. Keep the advertised subset consistent with the primary actions in the AGENTS.md table and the external catalog; the table may also document other in-app actions. Do not hand-write another action list in mcp.instructions, a skill, or an external skill; describe when to use actions there.
The http Option
Controls HTTP exposure:
| Value | Behavior | Use for |
|---|---|---|
| (omitted) | POST /_agent-native/actions/:name | Write operations (default) |
{ method: "GET" } | GET /_agent-native/actions/:name | Read-only queries |
{ method: "PUT"/"DELETE" } | matching verb | Update / delete |
{ method: "GET", path: "x" } | custom route path | Non-default path |
false | never exposed as HTTP | navigate, view-screen, internal |
Mutating actions (anything but GET) auto-refresh the UI on success — don't call refresh-screen after a normal action. Overrides (readOnly, parallelSafe) and exact trigger rules: references/action-fields.md.
Saves That Can Race
An action that writes a value a person or another agent may also be changing checks what it read:
- Server:
saveIfCurrentfrom@agent-native/core/save-conflict/servertakesread,writeandexpectedRevision. It checks and writes in one statement, confirms exactly one row changed, ignores a repeat of a save it already applied, and throws one typed conflict carrying the current value. UsesaveRevisionOf(value)as the revision, so no migration is needed and any writer moves it. SetrequireRevisionfor a write that replaces a whole value: a caller that read nothing gets the conflict, with the current value, and can redo its edit. - Reads return the same revision, and the schema takes it as
expectedRevisionwithEXPECTED_REVISION_DESCRIPTION. - Browser:
saveWithMergefrom@agent-native/core/save-conflictmerges field by field on a conflict and saves again, so most apps need no merge code.useSaveConflictPromptfrom@agent-native/toolkit/app/save-conflictis itsresolveOverlap: a person sees it only when both writers changed the same field, and can get the other version back. - Agents never see the prompt. They get the conflict and redo the edit on
details.current.
Outcomes are counted (save_outcome_counts, and save_conflict_prompt in the browser), so prompts that could have been automatic show up.
Names That Must Stay Unique
When a record's name must be unique in its parent (a file in a design, say), back the rule with a unique index and pick names with nextFreeName from @agent-native/core/free-name: name.html, then name-2.html, name-3.html (a slug whose alphabet has no - passes { separator: "_" }). Don't write another copy of that loop.
- Refusing: throw
nameTaken(record, name, suggestion)from@agent-native/core/free-name/server. It is a 409name_takenwhosedetails.suggestionis free; pass{ noWrite: true }from an action that declares it as a no-write error. Don't put internal ids in the message. - Creating from the UI: let the caller ask for the next free name instead of a refusal (Design's
create-filetakesifNameTaken: "next-free"), pick it on the server under the same lock as the insert, and return the saved name. Two tabs that both pickx-copy.htmlfrom their own list then both save. - When the picker can't see every name the index covers (other members' private records, say), let the insert claim it: on
isUniqueViolationfrom@agent-native/core/db, mark that name taken, pick again and retry a few times, then refuse. CRM'screate-crm-listdoes this for list slugs. - Agents get the refusal and retry with
details.suggestion, or edit the existing record if that was the intent.
Return Values
Return structured data (objects, arrays), never JSON.stringify() — the framework serializes the response and only tries to parse a returned string as JSON, which isn't the same contract.
run: async (args) => await fetchEvents(args.from, args.to); // good
run: async (args) => JSON.stringify(await fetchEvents(...)); // bad
A create/update result is read by more than the caller. These keys are well-known and survive result truncation:
id— the created or updated record. Pair it with a pure, synchronouslinkbuilder on the action (link: (result) => ({ url: buildDeepLink({ app, view, params: { id: result.id } }), label })) so MCP hosts and the desktop app surface an "Open …" deep link that lands in the editing view focused on the record; returningurl/urlPathin the result works too.nextRequiredAction— the name of the next tool to call when the operation is one step of a flow the agent should keep driving (nextRequiredAction: "update-slide"). Never phrase it as waiting for the user: an MCP/WebMCP/A2A caller cannot receive an in-app answer. The agent loop keeps this field in continuation prompts even when the rest of a large result is dropped, and MCP callers see it asNext: ….message/summary— the one-line status external callers read; everything else stays in the structured result.designSystem— when a record can link a brand or design system, expose it asdesignSystem: AgentDesignSystemContext | nullvialoadAgentDesignSystemContext(id, getDesignSystemAction)from core's shareddesign-system-agent-context. Reads get the bounded summary (scope: "summary", with anextline naming the full read); only the create action andget-design-systemitself pass{ full: true }.status: "unavailable"is notnull: keep the id and the message. Print it in text results withformatAgentDesignSystemContext; do not name the field anything else.
For actions that attach a chatUI renderer, use chatUI.projectResult to return
only the small structured fields the renderer needs. chatUI.when is evaluated
against the full successful result first; the projection is used live and saved
for interrupted-run recovery.
An action that hands control back to the user (question form, intake dialog) sets endsTurn: true; that hides it from MCP/WebMCP/A2A unless mcpTool: true is explicit — references/action-fields.md. For external-agent integrations, use the external-agents documentation slug listed by agent-native-docs.
An action the app's agent can call that the app's MCP catalog doesn't already serve needs a decision, or outside agents can reach it only through ask_app: mcpTool: true serves it to them (add a test that calls it over MCP), and mcpTool: false keeps it in-app, with a comment on that line saying why.
Every new action declares outputSchema: it types the action's return and is enforced strictly by default (guard:action-output-schema). Declare its failure codes with defineActionErrors and fail through them. Reach for _agentImages (attach images the agent can see), authorize (gate who may call it), or needsApproval (require human sign-off per call) only when the action needs that guarantee — examples in references/action-fields.md.
To test an action, start with checkActionProperties(action, { context }) from @agent-native/core/action-properties. It generates inputs from the zod schema, and fails on any throw that is not an action contract error, on a return its outputSchema rejects, and on an invalid input that reaches run. It needs fast-check as a devDependency, and it throws UnsupportedSchemaError for a schema shape it cannot generate unless you pass an override.
Write receipts
A write action that can check its own effect returns a plain-object result with a reserved _receipt, so the final answer is reconciled with what the write did, not with the model's reading of a JSON string that may be truncated:
import type { WriteReceipt } from "@agent-native/core/action";
const _receipt: WriteReceipt = {
changed: true,
verified: false,
summary: "Saved; panel 3 returned no rows.",
checks: [{ id: "panel-3", ok: false, detail: "0 rows" }],
};
return { id, _receipt };
verified is true (the effect was observed), false (checked and did not hold), or "unverified" (could not be checked); checks and warnings are optional. The agent loop reads the receipt before the result is stringified and truncated (summary 200 chars, 8 checks, 5 warnings):
verified: falseorchanged: falseforces one honest-reconciliation retry per turn: the model must say what the receipt shows and may not call the change visible or working. If the retry is spent, the answer is prefixed with the receipt block.verified: "unverified"only prefixes that note; no retry.- A receipt that is present but malformed counts as
unverified, never clean.changed: falsealso records the call ascompletedSideEffect: false, unless a write nested in the action also entered its handler: a receipt, likeretrySafe, speaks only for the action's own write. - Set
subject(the stable target, such as a dashboard id) so a laterchanged: true, verified: truereceipt for the same subject can supersede an earlier flagged one in the same turn. When the earlier receipt had failing or unverifiedchecks, the later receipts (from this action or another that writes the same subject) must carry anok: truecheck with the sameidfor each; a receipt without checks never clears one that had them. A flagged receipt with no failing checks is superseded only by the same action. Receipts without asubjectare never superseded.
A receipt is not an error channel. A write that did not achieve the requested state throws (fail()); return changed: false only for a benign no-op, such as the record already being in the requested state.
Failed Writes
The framework classifies a failed action from the writes it saw the call make: every database write (any statement that is not a read such as SELECT, SET or LOCK, and not the framework's own schema setup) and every fetch that is not GET, HEAD or OPTIONS. A rejection raised before any of those is "nothing saved", however it is thrown (fail(), a plain Error, a library error).
- Declare writes it cannot see. Before a disk write, child process,
node:http/httpsrequest or vendor SDK call, callnoteExternalWrite("<channel>"), e.g.noteExternalWrite("local-disk"). Without it, a failed call that already wrote looks retry-safe.guard:no-unobserved-writesfails new code that skips the call. A temp-only or retry-idempotent write can say why with// observed-write-ok: <reason>instead. withoutWriteObservation(fn)is only for framework bookkeeping (an audit row, a change marker, analytics) or a write a retry provably cannot repeat, such as one keyed by a deterministic id or dedup key. Never wrap the write the call exists to make.awaitthe work insidefn: a Drizzle query builder only runs when awaited, afterfnhas returned, sowithoutWriteObservation(() => db.insert(t).values(v))exempts nothing.retrySafesays this action's own write is safe to run again, so a failure after that write is not "unknown". It covers only this action's write. Don't set it on an action that appends, sends or charges unless the input carries an idempotency key.NoWriteErroris an override, not a requirement: most rejections need no label, but it wins over an observed write when the only write before the rejection is one a retry harmlessly repeats (such as uploads nobody has referenced yet), and the framework accepts it only for the call that raised it and only when no nested write action entered that call's handler.- A call that times out or loses its result stays "unknown", because it may still be running.
Frontend Hooks
Import from focused @agent-native/core/client/* entry points; the broad
@agent-native/core/client barrel is deprecated. Use action hooks, not
hand-written fetch("/_agent-native/actions/...").
import { useActionQuery, useActionMutation, callAction } from "@agent-native/core/client/hooks";
const { data: meals } = useActionQuery("list-meals", { date: "2025-01-01" }); // GET, types auto-inferred
const { mutate } = useActionMutation("log-meal"); // POST/PUT/DELETE
mutate({ name: "Salad", calories: 350 });
const people = await callAction("search-people", { query }, { method: "GET" }); // imperative (debounce, prefetch)
Don't add manual generics like useActionQuery<Meal[]>(...) — types come from .generated/action-types.d.ts. Mutations auto-invalidate all ["action"] query keys, so GET queries refetch. A revisit paints the persisted result for the signed-in user and org before that refetch; see references/action-fields.md for persistInBrowser: false.
A failed useActionMutation write shows one shared toast (WriteFailureToaster, mounted by AppProviders) when nothing else reports it. mutate toasts unless an onError (hook-level or per call) handles the failure; mutateAsync toasts only when its rejection ends up unhandled. errorNotification picks the mode: "auto" (default), "shared" (toast even beside an onError that only rolls back or logs), or "caller" (never: background saves, deliberate swallows, call sites that render the error themselves). errorLabel is an already-translated title. A fail() with a 4xx status shows its message as the toast text, a 5xx shows only the title because the server masks its text, and a 401 stays silent. For a write that is not a useActionMutation (a raw fetch upload, a swallowed catch), call reportWriteFailure(error, { label }) from @agent-native/core/client/write-failure.
When a query result varies by viewer or another client context that is not part of the action arguments, pass that stable context through queryKeyScope. It partitions only the local query cache; it is not sent to the action and never replaces server-side authorization.
How to Run (Agent)
pnpm action log-meal --name "Salad" --calories 350
CLI flags become action input fields (--key value or --key=value); the runner does not read or write files for --input or --output. The default template dispatches through core's runScript() in actions/run.ts. Action names are lowercase-with-hyphens (pnpm action my-action → actions/my-action.ts).
For a needsApproval action, the CLI checks parsed/defaulted input with caller cli. An interactive terminal shows the action and arguments and asks y/N (only y or yes runs). Without both stdin and stdout TTYs, ask the person to approve the specific call, then rerun the exact original pnpm action arguments with --approved appended. Never add --approved before the person approves. This reserved flag is removed before action input parsing and is harmless on ungated actions. See references/action-fields.md for approval details.
Custom /api/ Routes
Complete exception list — justified only when the caller isn't your own UI/agent, or the payload isn't JSON: file uploads (actions take JSON, not multipart), streaming (SSE/chunked needing direct H3 control), webhooks, OAuth callbacks (fixed redirect URL patterns), public unauthenticated endpoints (SEO/OG images, share links), binary/non-JSON responses.
Everything else — CRUD, settings, search, list/detail reads, auth state, anything the UI fetches as JSON — is an action. Needing middleware to scope a route to the current user is itself a signal it should be an action. Existing template /api/* CRUD routes are being migrated; do not add new ones.
Do / Don't
- Do keep one action, one job; document a reusable action (when to use it, key args, return fields to preserve) in
AGENTS.mdonce it's called from outside one narrow screen; promote workflow-heavy actions (provider-backed, cross-app, MCP/A2A, multi-step) into a skill. - Do use
fail(message, { errorCode, statusCode })for user-friendly errors and import primitives from@agent-native/core(/action) instead of redefining them; use the coreupload-imageaction oruploadFile()for durable images/files — never base64 into SQL, markdown, or action results. - Do signal failure by throwing, using
fail()for expected caller-readable failures. Never return{ error: ... }as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults. - Do use
fail()rather than a bareErrorfor caller-readable failures. It carries the action's message,errorCode, anddetailsto the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults. - Do give
fail()the status that matches the cause: it defaults to400, anduseActionQueryretries only429,502,503, and504. Mutations do not retry; use transient statuses only for retryable failures. - Do validate inputs before the first write. A rejection raised before any write the framework can see is "nothing saved", so the agent can fix its request and retry. Don't reorder code just to add labels. See Failed Writes.
- Do render
actionErrorMessage(error) ?? yourCopyin UI, never bareerror.message. The message keeps anAction <name> failed:prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, andundefinedwhen nothing did (network drop, proxy HTML page), which is why the fallback is not optional. - Do pass a real
errorCodewhen the agent should branch on the failure rather than re-read it. Codes other than the defaultaction_failedare appended to the tool result as(errorCode: not_found), on both the in-app agent and MCP.detailsfollow as anError details: {...}JSON line, and asstructuredContent.errorover MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either. - Don't re-export actions as REST —
/_agent-native/actions/:nameis already the REST surface; duplicating it under/api/*hides the operation from agents. - Don't reach for provider integrations,
authorize,needsApproval, or_agentImageswithout checkingreferences/first — each has sharp edges covered there, not here.
Troubleshooting
- Action not found / type mismatch — filename must match the command (
pnpm action foo-bar→actions/foo-bar.ts), and the action must be the file's default export. MultipledefineActionnamed exports in one file register only the default; split them into one file each. - Args not parsing — use
--key value/--key=value; boolean flags are--flag(sets"true"). - Frontend 405 —
http.methoddoesn't match the hook (useActionQueryfor GET,useActionMutationfor POST/PUT/DELETE). - Frontend gets undefined — action must return structured data, not
JSON.stringify().
References
references/provider-apis.md— wiring a credentialed provider (HubSpot, Gong, Slack, …) for querying, reporting, or cross-source research.references/action-fields.md—outputSchema,authorize,needsApproval,_agentImages, and exact auto-refresh rules.references/examples.md— a second worked example and legacy bare-export patterns.
Related Skills
- storing-data — Actions read/write data in SQL
- delegate-to-agent — The agent invokes actions via
pnpm action <name> - real-time-sync — Database writes from actions trigger change events to update the UI
- adding-a-feature — Actions are area 2 of the four-area checklist
- client-methods — Client code uses named helpers/hooks instead of raw REST calls
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |