Saas Agent Toolkit

SaaS Agent Toolkit

Overview

Use this skill when a user asks how to make a SaaS product "agent-usable" rather than only human-usable.

This skill reframes product capabilities into a stable execution model:

1. Connectors layer: auth and event plumbing 2. Tools layer: six reusable tool shapes 3. Policy layer: permissions, approvals, and reliability guardrails

Workflow

1. Scope target SaaS domain and entities. 2. Define the 3-layer architecture. 3. Map capabilities into the six tool shapes. 4. Add guardrails (auth, allowlists, idempotency, audit). 5. Produce a concrete rollout plan and KPI set.

Step 1: Scope Domain

Capture:

• Product/system (for example Zendesk, Salesforce, Jira, Notion)
• Core entities (ticket, contact, issue, page, deal, order)
• High-risk actions (payment, delete, external publish, permission change)
• Success outcome (speed, quality, cost, reliability)

Step 2: Build 3-Layer Architecture

Design these layers explicitly:

1. Connectors: OAuth/API key, webhook ingestion, identity mapping, optional SCIM. 2. Tools: Search, Summarize, Draft, Update, Notify, Approve. 3. Policy & Guardrails: RBAC, budgets, rate limits, PII controls, logging, retries.

Design principle: Prefer predictable, auditable, rollback-safe operations over "smart but opaque" behavior.

Step 3: Define Tool Contracts

Use six stable tool contracts:

1. Search: locate entities and relationships. 2. Summarize: produce structured, citation-backed takeaways. 3. Draft: generate submit-ready drafts without auto-sending. 4. Update: write bounded, idempotent changes back to systems. 5. Notify: close loops with owners/watchers/approvers. 6. Approve: enforce human gating for high-risk operations.

Read references/tool-contracts.md for function templates and I/O expectations.

Step 4: Add Mandatory Guardrails

Apply all of the following:

• Explicit error taxonomy (401, 403, 404, empty, conflict, timeout)
• Idempotency key for mutating actions
• Field allowlist for Update (no unrestricted patch)
• Citation requirement for Summarize
• Dry-run and draft-only defaults for user-facing output
• Approval gates for high-risk categories
• Full audit trail: who requested, who approved, what changed, when, result

Read references/approval-and-audit.md for standard approval and audit schema.

Step 5: Produce Deliverables

Return output in this structure:

1. Domain scope and entities 2. 3-layer architecture 3. Tool contract table (six tools) 4. Guardrail design 5. Example end-to-end workflow 6. Rollout plan (0-30, 31-90, 90+ days) 7. KPI table 8. Top unresolved risk

KPI minimums:

• task completion rate
• first-call success
• API success rate
• p95 latency
• integration lead time
• unit outcome cost

Example Workflow Patterns

Use references/workflow-patterns.md for ready-to-adapt flows:

• customer support triage and response
• sales follow-up automation
• incident assistant with approval-gated external updates

Approval and Audit Baseline

High-Risk Action Classes

Require approval for:

• payment/refund/price/contract changes
• delete or bulk-mutation operations
• external broadcast (email, announcement, social)
• production config change or rollback
• permission escalation

Approval Modes

Blocking

• Agent generates approval card.
• Execution is blocked until human approval is received.

Queue-Based

• Agent pushes approval request into a queue/workflow system.
• Execution continues only from approval callback/webhook.

Approval Schema

{
  "approval_id": "apr_...",
  "action": "refund_order",
  "target": {"type":"order", "id":"ord_123"},
  "risk_level": "high",
  "requested_by": "agent:ops-assistant",
  "approvers": ["user:finance_manager"],
  "expires_at": "2026-02-25T12:00:00Z",
  "status": "pending"
}

Audit Schema

{
  "event_id": "evt_...",
  "timestamp": "2026-02-24T13:00:00Z",
  "requested_by": "agent:ops-assistant",
  "approved_by": "user:finance_manager",
  "action": "refund_order",
  "target": {"type":"order", "id":"ord_123"},
  "before": {"status":"paid"},
  "after": {"status":"refunded"},
  "result": "success",
  "idempotency_key": "sha256(...)",
  "trace_id": "trace_..."
}

Failure Handling

• Retry only idempotent operations.
• On permanent failure, emit notification with remediation owner.
• Preserve failed action payload and error class for incident review.

Tool Contracts

Search

Goal: Find the right entity before taking action.

Recommended functions:

search_entities(app, entity_type, filters, query, limit=20)
get_entity(app, entity_type, id, fields)
list_related(app, entity_type, id, relation_type, filters)

Output pattern:

[
  {"id":"...", "title":"...", "updated_at":"...", "snippet":"...", "score":0.92}
]

Notes:

• Return candidates first for disambiguation.
• Keep default result size small (5-20) and paginate.

Summarize

Goal: Convert long context into executable information.

Recommended functions:

summarize(content, schema, citations=true)
summarize_entity(app, entity_type, id, schema, citations=true)

Required output sections:

• conclusion
• evidence/citations
• next actions
• risks
• open questions

Rules:

• Every key claim should map to source ids/links.
• Never invent missing fields (for example amount, date, owner).

Draft

Goal: Generate actionable drafts without auto-submitting.

Recommended functions:

draft_reply(context, tone, constraints, required_points)
draft_doc(template, inputs, sections)
draft_variants(n, style_tags)

Rules:

• Include hard constraints: must include, must avoid, legal/SLA limits.
• Default to draft/internal-note state.

Update

Goal: Write decisions back into SaaS safely.

Recommended functions:

add_comment(entity, text, visibility)
set_status(entity, status)
assign_owner(entity, owner_id)
set_fields(entity, patch)
add_tags(entity, tags)
remove_tags(entity, tags)
link_entities(a, b, relation_type)

Rules:

• Require idempotency key for mutating calls.
• Use field allowlist; reject unrestricted patch updates.

Notify

Goal: Ensure stakeholders know what to do next.

Recommended functions:

notify(channel, recipients, message, severity, links, attachments)
create_task(app, title, description, assignee, due_date)
escalate(entity, reason, to_team)

Notification minimum:

• object link
• short summary (3-5 lines)
• proposed next step and owner
• approval action path if needed

Approve

Goal: Gate high-risk operations with human confirmation.

Recommended functions:

request_approval(action, payload, risk_level, approvers, expiry)
execute_approved(approval_id)

Rules:

• Re-validate state and permissions before execution.
• Expire stale approvals and force re-request.

Workflow Patterns

Pattern A: Support Triage (Zendesk/Intercom)

1. Trigger: new ticket webhook. 2. Search: find similar tickets and customer history. 3. Summarize: issue, prior attempts, current status. 4. Draft: response draft plus missing-info checklist. 5. Update: set priority/tags/owner for low-risk actions. 6. Notify: send summary to assignee. 7. Approve: route refund/compensation actions to approver.

Pattern B: Sales Follow-Up (HubSpot/Salesforce)

1. Trigger: call note/transcript arrives. 2. Summarize: pain points, budget, timeline, decision process. 3. Update: write next_step, stage, and follow-up task to CRM. 4. Draft: follow-up email variants. 5. Notify: remind account owner to review/send. 6. Approve: gate price/contract exceptions.

Pattern C: Incident Assistant (PagerDuty + Datadog + Jira + Slack)

1. Trigger: production alert. 2. Search: gather logs, recent deployments, related pull requests. 3. Summarize: impact, timeline, likely root cause. 4. Draft: internal/external status update drafts. 5. Update: create incident issue and sync status. 6. Notify: alert incident commander and stakeholder channel. 7. Approve: require approval for public status-page updates.