Agent Workflows

This guide explains how to turn AuraBoot metadata into useful agent workflows. The goal is not to make the model free-form. The goal is to give it well-described tools, strict schemas, and a guarded path for business operations.

Prerequisites

Before enabling agent workflows, make sure the basic platform metadata is healthy:

Requirement	Why it matters
Models have readable names and field descriptions	The model needs domain context
Commands are published and permissioned	Agents execute through commands
Command input schemas are strict	Tool calls need reliable parameters
Risk levels are assigned	Confirmation policy depends on risk
Audit logging is enabled	Agent actions must be traceable

If the metadata is weak, the agent will still run, but it will ask more clarification questions and choose tools less reliably.

Configure an LLM Provider

AuraBoot reads LLM configuration from the platform cloud configuration service. A provider record should define:

Provider code, such as openai, anthropic, deepseek, or a custom OpenAI-compatible provider
API format, usually chat_completions or messages
Base URL when using a compatible gateway
Default model
API key
Token limits and timeout policy

Use one provider first. Add multiple providers only when you have a clear routing need, such as a fast model for summaries and a stronger model for planning.

Define an Agent

An agent definition should be small and concrete.

Field	Guidance
Code	Stable identifier, such as `sales-assistant`
Name	User-facing name
System instruction	Role, scope, and boundaries
Default model	Model to use unless overridden
Allowed tools	Narrow list of tool codes or capability groups
Guardrails	Confirmation, budget, max steps, provider policy

Avoid broad instructions such as "manage the whole business". Prefer scoped agents such as "help sales users inspect leads, draft follow-ups, and create task records".

Expose Tools

The best tools are usually existing commands and named queries.

Tool source	Best for	Notes
DSL command	Create, update, delete, state transition	Uses permissions, validation, audit
Named query	Analytics and read-heavy questions	Keep parameters explicit
Native tool	Integration-specific actions	Add a strict contract
Workflow action	Long-running business processes	Prefer approval for risky steps

Each tool needs a clear purpose, input schema, output schema, and risk policy. Do not expose internal maintenance APIs as agent tools unless they are already safe for delegated execution.

Add Agent Hints

Agent hints are short usage descriptions attached to capabilities. They help the model choose the right tool.

Good hint:

Use this command when a sales user wants to qualify a lead after confirming budget, decision maker, and expected close date. Do not use it for leads still missing required discovery fields.

Weak hint:

Update lead.

The stronger hint tells the model when to use the command, when not to use it, and which business preconditions matter.

Set Confirmation Policy

Map tool risk to user confirmation.

Operation	Suggested policy
Read-only lookup	No confirmation
Draft creation	No confirmation or ask once
Status transition	Ask once
Delete or irreversible action	Always ask
Financial, legal, or external side effect	Approval required

Confirmation is not only a UI detail. It is part of the agent contract, so it should be reviewed with the same discipline as command permissions.

Run a Test Conversation

Start with a simple scenario:

Open AuraBot from a page with known model context
Ask a read-only question about the current list
Ask the agent to create a draft record
Confirm the action if prompted
Open the created record and verify field values
Inspect the trace and audit entry

The trace should show the model call, selected tool, arguments, command result, and final response. If the wrong tool was selected, improve the tool contract before changing prompts.

Troubleshooting

Symptom	Likely cause	Fix
Agent says no provider is configured	Missing or disabled LLM provider	Add a cloud config provider record
Agent cannot run a command	User lacks permission or command is unpublished	Fix permission or publish the command
Agent asks too many questions	Tool schemas or field descriptions are vague	Improve model and command metadata
Agent selects the wrong tool	Tool purpose overlaps with another tool	Add `whenToUse` and `whenNotToUse` guidance
Tool call fails validation	Input schema does not match command requirements	Align the command schema and examples

Production Checklist

Provider keys are stored in platform configuration, not in frontend code
High-risk commands require confirmation or approval
Agent tools have current contracts
Tool contracts are regenerated after capability changes
Trace retention and audit retention match your compliance needs
A small set of real workflows has been tested end-to-end

Next Steps

Agent System — Architecture and runtime model
AI Copilot — User-facing assistant behavior
Commands — Define the operations agents can call