Agents

Agents are first-class actors that can read, write, and act on records using LLMs. Each agent has its own roles, tools, and audit trail — they are indistinguishable from users in the permission and audit systems.

Define an agent

// @noverify
import { useCreateAgentDefinition } from "@stndrds/react";

const create = useCreateAgentDefinition();

create.mutate({
  name: "support-agent",
  systemPrompt: "You triage incoming support requests...",
  model: { provider: "anthropic", model: "claude-sonnet-4-5" },
  tools: ["search_contacts", "create_note"],
});

CreateAgentDefinitionInput requires name, systemPrompt, and model. tools is an optional array of tool names registered in the schema. Other optional fields include description, maxIterations, canDelegate, maxDepth, maxTreeCostUsd, and schedule.

Agent identity

Each agent_definitions row triggers creation of an actor row (type='agent') via a SQL trigger. The agent shows up everywhere actors do — in audit logs, in role assignments via useActorRoles(actorId), and in the actor picker. Assign roles to an agent the same way you would to a user.

Audit delegation chain

When an agent acts on behalf of a user, AsyncLocalStorage carries three fields:

• actorId — who is executing right now (the agent or the user)
• triggeredByActorId — the actor that started this step
• rootActorId — the originating human user at the top of the chain

This lets you write audit queries like "show everything Claude did for Alice yesterday" by filtering on rootActorId = alice and actorId = agent.

Tools

Tools are typed functions registered in the schema that agents can call. The agent runtime validates inputs and routes calls through standards' adapters. A tool named "search_contacts" maps to a resolver registered in the backend — no ad-hoc function passing.

Trigger an agent

• From a UI button — call useCreateAgentSession(definitionId) and .mutate({ input }) on user action.
• From a webhook — the API exposes a session-start endpoint; POST to it with an API key.
• From a record event — use agent triggers (useCreateAgentTrigger) to fire automatically when a record changes.
• On a schedule — set a cron expression on the agent definition; the BullMQScheduleAdapter enqueues a scheduled-job payload that the runtime translates into a launchRun call.