Agent Actions

Rule

Actions in actions/ are the single source of truth for app operations. The agent calls them as tools, and the frontend calls them through useActionQuery / useActionMutation. The framework owns the HTTP transport behind those hooks. No duplicate /api/ routes needed.

Before creating any custom REST/API route for app data, inspect actions/ and the action table in AGENTS.md. If an action already exists, call it directly from the agent or with useActionQuery / useActionMutation from the UI. If the capability is missing, create or update a defineAction. Do not add /api/*, server/routes/*, or other pass-through endpoints whose main job is to call, repackage, or re-export an action.

Why

Actions give the agent callable tools with structured input/output, AND they give the frontend a typed client contract through hooks. One implementation serves both the agent and the UI. They keep the agent's chat context clean, they're reusable, and they can be tested independently.

Keep the Action Surface Small and Orthogonal

Every agent-exposed action is a tool in the model's context window. There is a real cost to each one: more tools means more for the model to read, disambiguate, and choose between, which degrades tool-selection quality. Treat the action list like an API you have to maintain — add the fewest, most orthogonal actions that cover the capability, not one per UI affordance.