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.