Agents

Agent definitions use the same two visibility values as records: "workspace" and "private". Runtime agents default to workspace visibility.

Runtime visibility

Pass visibility when creating or updating an agent definition:

const agent = await client.createAgentDefinition({
  name: "Research assistant",
  systemPrompt: "Research the requested topic and cite the supplied sources.",
  model: { provider: "anthropic", model: "claude-sonnet-5" },
  visibility: "private",
});

For a private agent, only its owner can find, launch, or configure the definition. Hidden definitions, runs, sessions, actor-directory entries, roles, and environment variables return the same not-found result as missing resources. The running agent can still resolve its own definition, but another agent cannot discover or delegate to it.

Only the actor who created a workspace agent may move it to private visibility. That transition sets ownedBy to the caller; any other actor with update permission receives ForbiddenError. Only the owner may return a private agent to workspace visibility.

Moving an agent to private visibility unregisters its schedule and excludes its triggers from background dispatch. Returning it to workspace visibility registers an enabled schedule again; configured triggers become eligible for dispatch without being recreated.

The React mutation inputs CreateAgentDefinitionInput and UpdateAgentDefinitionInput accept the same visibility field. useAgentDefinitions() returns only definitions visible to the current actor.

Trigger conditions

A trigger's optional filter narrows which events launch a run. Rules name an attribute, an operator, and a value, and a rule the matcher cannot resolve evaluates to false — a trigger never fires on an event its filter does not positively match.

For record.* triggers, rules address the object's attributes and its system columns. A form.submitted trigger has no object, so its rules address the submission event itself: formId, formName, submissionId, and createdBy.

await client.createAgentTrigger({
  definitionId: agent.id,
  eventType: "form.submitted",
  filter: {
    combinator: "and",
    rules: [{ attribute: "formName", operator: "is", value: "kyc-intake" }],
  },
});

Filtering a form trigger on a slot value is not supported: those attributes belong to the records the submission creates, not to the event. Use a record.created trigger on the target object instead.

Fluent agent builder

Code-declared agents are system definitions, so they must remain workspace-visible:

const assistant = agent({ name: "Assistant" })
  .visibility("workspace")
  .systemPrompt("Help users complete workspace tasks.")
  .model("anthropic", "claude-sonnet-5")
  .build();

visibility("workspace") is optional because it is the builder default. Calling visibility("private") on a system agent fails validation: private ownership is assigned only when a runtime agent is created by an authenticated actor.