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.

Built-in skills

@stndrds/runtime ships BUILT_IN_SKILLS that are loaded into the agent system prompt on demand: document-generation (DOCX/PDF/PPTX/XLSX via LibreOffice and the docx npm package), browser-automation (drive Chromium with playwright-cli inside the sandbox to inspect UI state, capture screenshots, and debug console/network failures), and ui (product-language tour of the app, kept jargon-free for agents talking to end-users). The E2B sandbox template now installs playwright@1.60.0 and pre-fetches Chromium so the browser-automation skill works out of the box.

Environment variables

Agents can read tenant-scoped or per-agent environment variables at runtime. Values are stored encrypted (pgcrypto) and resolved on each execution — only metadata is ever returned to the client. The resolved keys are injected into the agent sandbox and appended to the system prompt as an ## Available Environment Variables section so the model knows which $KEY_NAME references are valid in shell tool calls.

Per-agent values override tenant-level values for the same key. Archiving an agent deletes its scoped variables.

Manage them from React via the env var hooks:

// @noverify
import { useAgentEnvVars, useUpsertAgentEnvVar, useDeleteEnvVar } from "@stndrds/react";

function AgentEnvVars({ agentId }: { agentId: string }) {
  const { data: entries = [] } = useAgentEnvVars(agentId);
  const upsert = useUpsertAgentEnvVar(agentId);
  const remove = useDeleteEnvVar({ agentId });

  return (
    <div>
      {entries.map((e) => (
        <div key={e.id}>
          {e.key} <button onClick={() => remove.mutate(e.id)}>delete</button>
        </div>
      ))}
      <button onClick={() => upsert.mutate({ key: "STRIPE_KEY", value: "sk_test_..." })}>
        add
      </button>
    </div>
  );
}

Tenant-wide vars use useEnvVars / useUpsertEnvVar instead. The settings UI exposes WorkspaceEnvVarsSection for the tenant scope and an env vars tab on AgentSettingsDialog for the per-agent scope. Read and write require the env-vars system permission.

Tenant system prompt

A tenant can define one system prompt that is prepended to every agent's own systemPrompt for that workspace — use it for workspace-wide tone, policy, or context that every agent should share. When no tenant prompt is set, the runtime falls back to the static config prefix, and a failed settings read never blocks execution.

Manage it from React with useTenantSettings / useUpdateTenantSettings:

// @noverify
import { useTenantSettings, useUpdateTenantSettings } from "@stndrds/react";

function WorkspacePrompt() {
  const { data: settings } = useTenantSettings();
  const update = useUpdateTenantSettings();

  return (
    <textarea
      defaultValue={settings?.systemPrompt ?? ""}
      onBlur={(e) => update.mutate({ systemPrompt: e.target.value || null })}
    />
  );
}

The settings UI exposes WorkspaceSystemPromptSection (from @stndrds/ui/settings-dialog) for this tenant scope. Reading the prompt requires the workspace read permission and saving requires workspace update.

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.