AI Agent Access

AI Agent Access lets your team connect approved assistants to CleanEstimate Pro without sharing a full user login. Each agent gets its own token, its own tool permissions, and a full activity trail.

What It Is

Agent access is designed for cases where you want an assistant to help with real work inside CE Pro, such as reviewing inbox activity, checking estimates, or supporting your team with fast answers.

Instead of giving the assistant broad account access, CE Pro creates a scoped token that limits what the agent can do. Only members who can manage the team (manage_team) can view or manage agent tokens; everyone else sees a read-only notice.

Each tool request is checked against the token creator's current active membership, permissions, and organization/location scope. Deactivation, permission changes, role changes, and location reassignment therefore affect subsequent requests; a token does not preserve its creator's old access.

Where To Set It Up

Go to Admin > AI > Agents (/ai/agents).

From this page you can:

• Create a new agent token
• Choose which tools the token can use
• Keep the token read-only or enable guarded write actions
• Revoke a token at any time
• Review recent agent activity

Tokens

Every token starts with the prefix cea_. The full token is shown exactly once, right after you create it — copy it before leaving the page, because CE Pro never stores or displays it again. The token list shows only the first 12 characters (the prefix) so you can tell tokens apart.

A token can optionally get an expiration date. Agent access is refused whenever the org-wide AI access switch (Admin > AI) is off, even for a valid, unexpired token — see AI Features Overview.

Read-Only Access

New tokens default to CE Pro's five read tools. A read-only agent can help your team by retrieving information without changing customer records.

Guarded Write Access

If you enable write access, CE Pro still keeps the scope intentionally small — exactly two guarded actions exist today:

Every write call requires a second confirmation. The first call (without confirmation) is refused with a human-readable preview of the pending change; the agent (or its operator) must resend the same call with confirmation set before CE Pro applies it. A write that's never confirmed makes no change and still appears in the activity log as requiring confirmation.

Revoking A Token

Revoke a token from the Tokens list at any time. Revoking is immediate and permanent — the agent's next call is refused, and a revoked token cannot be un-revoked (create a new one instead). Revoking an already-revoked token is a no-op.

Activity And Audit Trail

Every agent request is logged — including refused calls (unknown tool, disallowed tool, a write awaiting confirmation, or a failure), not just successful ones. Your team can review:

• Which token was used
• Which tool the agent called
• When the action happened
• Whether it succeeded or failed

Use the activity log to confirm behavior, investigate mistakes, and decide whether an agent needs broader or narrower access.

For Developers: The Agent Endpoint

Agents call a single JSON endpoint, not a full API surface:

POST /api/ai/agent
Authorization: Bearer cea_...
Content-Type: application/json

{
  "tool": "search_clients",
  "args": { "search": "Jordan" },
  "confirm": false,
  "sessionId": "optional-session-id",
  "requestId": "optional-idempotency-id"
}

tool and args are required; confirm, sessionId, and requestId are optional. confirm: true is required on the two write tools before CE Pro applies the change. The endpoint is rate-limited per client IP.

A successful call returns { "ok": true, "result": ... }. An error returns { "error": "<code>" } (a pending write also returns a preview string):

Agent tool calls do not spend AI credit — the usage tiles on the AI hub never grow from agent activity.

Best Practices

• Start with read-only access and expand later only if needed.
• Create separate tokens for separate assistants or workflows.
• Revoke any token you no longer use.
• Review activity logs regularly, especially after enabling write access.
• Limit write access to trusted workflows with clear human oversight.