AI Agent

AI Agent is Lubb's built-in, Claude-powered copilot (previously branded "Adam"). It chats with your team in plain language, can read data across your Lubb grids, and — when a task calls for a change — proposes the write and waits for a human to approve it before anything happens. Admins use it directly through chat and also configure it as a set of named, policy-bounded agents that can run on a schedule or react to business events (a new invoice, an imported bank statement, and so on).

What you can do

• Chat with the copilot — hold an ongoing conversation with the AI Agent; it remembers context across turns within a conversation and can be scoped to a specific named agent.
• Review the Approvals queue — every proposed write action (creating/updating a record, sending an email or SMS, running a business action) lands here first. You see the exact tool, a plain-English summary, and the full payload before deciding.
• Approve or reject proposed actions — approve to let the action proceed, or reject with a required reason; only an admin holding the configured approver role (or the tenant owner) can decide.
• Read the Action Log — a full audit trail of every tool call any turn made, successful or not, including denied, pending, and expired attempts, with timing and error detail.
• Define named Agents — configure a reusable agent: its task prompt, an optional system-prompt addition, which tools and grids it's allowed to touch, a maximum number of write actions per run, which user identity it runs as, and whether it may only be driven interactively from chat.
• Run an agent on demand — trigger an enabled agent immediately from its row ("Run now") and watch its progress land in Agent Runs.
• Review Agent Runs — see each execution's trigger (manual/scheduled), status, duration, how many actions it took, and its final report or error.
• Subscribe agents to business events — bind an event name (e.g. an invoice being submitted) to an agent so it runs automatically when that event fires for a tenant.
• Inspect Platform Events — see the queue of emitted business events and whether each has been dispatched to its subscribers.
• Configure the AI Agent per tenant — turn it on/off, flip a kill switch, choose a model, enable/disable write tools, set the approver role and approval timeout, and add extra system-prompt instructions.

Common tasks

1. Start a conversation with the AI Agent Open the AI Agent chat, create a new conversation (optionally scoped to a named agent), and type your request. The copilot replies in the same thread; later turns automatically resume the same session so it keeps context.

2. Ask the AI Agent to make a change Describe the change you want (e.g. "send this customer a follow-up email"). If write tools are enabled for your tenant, the AI Agent doesn't act immediately — it creates a Pending row in the Approvals queue and waits.

3. Review and approve a proposed action Open Einstein AI Approvals, find the Pending row, check the Tool, Summary and full Details (the exact outbound message or record payload), then click Approve. The AI Agent's background process picks up the status change and carries out the action.

4. Reject a proposed action From the same queue, click Reject on a Pending row and supply a required reason. The action never runs, and the reason is stored on the request.

5. Set up a scheduled or event-driven agent Create an Agent with a task prompt, tool/grid allowlist and max-actions budget, choose the user it runs as, then either trigger it manually with "Run now" or bind it to a business event in Event Subscriptions so it fires automatically when that event occurs.

6. Investigate what an agent did Open Agent Runs to see a run's status, duration and report, or open the Einstein AI Action Log to see every individual tool call (including denied or errored ones) with its input, output and outcome.

Data model

• AiAgentSettings — per-tenant singleton: enabled flag, kill switch, model, write-tools toggle, approver role, approval timeout, extra system prompt.
• AiAgentConversation — one chat thread, its status, and its persistent Claude CLI session id; may be scoped to a named AgentProfile.
• AiAgentMessage — one normalized transcript row per conversation turn (role, text, duration, error).
• AiAgentApprovalRequest — a pending/decided human approval gate for a write or outbound tool call, with the tool name, full input payload, summary, status and decision metadata.
• AiAgentActionLog — audit trail of every tool call a turn made (success, error, denied, pending-approval or expired), with before/after snapshots and duration.
• AgentProfile — a named, policy-bounded agent: task/system prompt, tool and grid allowlists, max actions per run, model, run-as user, and whether it's chat-only.
• AgentRun — one execution of an AgentProfile: trigger (manual/scheduled), status, timing, action count and final report/error.
• PlatformEvent — an emitted business event (e.g. invoice submitted, statement imported) queued for agent dispatch.
• EventSubscription — binds an event name to the AgentProfile that should run when that event lands for a tenant (or every tenant, if unscoped).

Configuration & integrations

• Requires a configured Claude/Anthropic model — each tenant's AiAgentSettings picks the model, and a per-AgentProfile model override is also available.
• Write actions (creating/updating records, sending email/SMS, running business actions) are gated behind human approval whenever enable_write_tools is on; this gate is enforced unconditionally in code, not by configuration.
• The approver role defaults to admin but is configurable per tenant; the tenant owner can always decide, regardless of that setting.
• A tenant-level kill switch is available to halt the AI Agent independent of the enabled flag.
• The module runs on Lubb's ERP-hub sites; access to its grids (Approvals, Agents, Agent Runs, Action Log, Event Subscriptions, Platform Events) is admin-only.

API reference

Chat and settings have dedicated endpoints; the operational grids (Approvals, Agents, Agent Runs, Action Log, Event Subscriptions, Platform Events) use Lubb's generic grid CRUD surface.

Dedicated AI Agent endpoints:

• GET /ai-agent/settings — read this tenant's AI Agent configuration.
• PUT /ai-agent/settings — update (or create) this tenant's AI Agent settings.
• GET /ai-agent/conversations — list this tenant's conversations, optionally filtered by agent profile name.
• POST /ai-agent/conversations — start a new conversation, optionally bound to a named agent.
• GET /ai-agent/conversations/{conversation_id} — fetch a conversation with its full message transcript.
• DELETE /ai-agent/conversations/{conversation_id} — soft-delete a conversation.
• POST /ai-agent/conversations/{conversation_id}/messages — send one chat turn and receive the reply plus any resulting action-log entries.

Generic grid CRUD (slugs: ai-agent-approvals, agent-profiles, agent-runs, ai-agent-action-log, event-subscriptions, platform-events):

• GET /grid/{slug}/data — list/search rows for a grid.
• GET /grid/{slug}/stats — grid summary counts (e.g. total/pending/approved/rejected).
• POST /grid/{slug} — create a row (only where the grid allows creation, e.g. Agents, Event Subscriptions).
• PUT /grid/{slug}/{row_id} — update a row (where editable).
• DELETE /grid/{slug}/{row_id} — delete a row (where allowed).
• POST /grid/{slug}/action/{key} — run a row action, e.g. approve / reject on Einstein AI Approvals, or run_now on Agents.