Agent Tools

An AnyDB agent is an AI assistant in a workspace that runs on a trigger or schedule, reads data through AnyDB tools, and can change or send only what its saved scope allows. These tools let an assistant draft an agent, check it, try it without side effects, publish it, and review what it did.

Agents need workspace admin access and a Business or Enterprise plan. An agent runs as the person who saves it, with that person's access.

Available tools

Tool	What it does
anydb_save_agent	Creates or updates an agent draft. Saving never runs the agent and never spends AI tokens.
anydb_list_agents	Lists the agent drafts in a workspace with their version, validation and trial result, and linked workflow.
anydb_get_agent	Reads one draft: prompt, trigger, saved scope, version, evidence for the current revision, and the workflowId used to run or enable it.
anydb_validate_agent	Has an AI review the draft's prompt for clarity, scope, and supported capabilities. Spends team AI credits.
anydb_test_agent	Runs the draft in test mode with real reads and previewed writes and emails. Spends team AI credits.
anydb_publish_agent	Publishes a validated revision so it can run live.
anydb_delete_agent	Permanently deletes an agent, its draft, and the workflow that publishing created.
anydb_list_agent_runs	Lists validation, test, and live runs, newest first, optionally for one agent.
anydb_get_agent_run	Reads one run: outcome, each tool call, emails and record changes, token usage, and cost.

Recommended sequence

1. Call anydb_save_agent without an id to create a draft. To update one, pass its id and the version from your last anydb_get_agent. A stale version is refused so nothing is overwritten.
2. Call anydb_validate_agent. A blocking clarification question means validation did not pass: edit the prompt with anydb_save_agent and validate again. The feedback can include up to three revisedPrompts, one marked recommended.
3. Optionally call anydb_test_agent, which is worth doing for an agent that emails or changes data. A clean test proves the agent completed, not that its output is right, so read the run with anydb_get_agent_run.
4. Call anydb_publish_agent with the draft's current version. Publishing is refused unless the same revision has a successful validation.
5. Start the agent. Publishing leaves a new workflow disabled unless you pass enable: true. You can also enable it with anydb_update_workflow, or run it once with anydb_execute_workflow using the agent's workflowId.

Editing any behavior-changing setting creates a new draft revision that must be validated again. Validation and test results apply only to the exact revision they ran against.

What an agent may do

An agent's mutationScope is the whole of what it may change or send:

Setting	Controls
fields	The cell positions it may write.
recordIds	The records it may target.
emailRecipients	Who it may email.
artifacts	The reports and document templates it may email. readReports optionally limits which reports it may run and read; leave it out to let the agent run and read any report its owner can read.
createRecords	Advanced rules for the typed child records the agent may create. See the authoring guide.
maxEmails, maxRecordChanges	Optional per-run limits (1 to 100). The run stops before the next email or change.

An agent with no mutationScope can only read. When you update a draft, send its mutationScope back unchanged: a save that leaves it out removes it, and the response carries a mutation_scope_removed warning.

promptReferences bind a person, record, type, or field to the prompt by id, as an @mention does in the browser. Send the draft's promptReferences back unchanged when you update it.

Triggers

An agent uses the same triggers as workflows: trigger_manual, trigger_on_schedule, trigger_on_record_create, trigger_on_record_update, trigger_on_form_submit, and trigger_plugin_event. Pass the trigger's own settings in inputProperties, or {} for a manual trigger.

Review what an agent did

anydb_get_agent_run returns a short summary by default. Pass detail: "full" for every tool call with its arguments and results, which can be 80 KB or more, and use page for large runs. The model's own summary is an explanation; the tool calls are the evidence.

Tools inside an agent run

During a run the agent itself uses a separate set of tools. You do not call them directly, but they appear in a run's tool calls:

Tool	What it does
anydb_agent_read_record	Reads a record's name, type, in-scope field values, locks, and revision.
anydb_agent_update_fields	Updates existing in-scope fields with literal values.
anydb_agent_set_cell_lock	Sets the lock flag on one in-scope cell.
anydb_agent_create_record	Creates a typed child record under a saved parent, type, and initial-field rule.
anydb_agent_send_email	Sends one plain-text email to the agent's saved recipients.
anydb_agent_email_report	Emails the CSV or XLSX export of a saved-scope report to the saved recipients.
anydb_agent_email_document	Renders a saved-scope document template for a record and emails the result to the saved recipients.

In a test run every write and email is a server-controlled preview, so nothing is sent.