docs(email): partner-facing Capability & API Spec (v2.0)#1619
Conversation
Self-contained HTML spec for the Email Triage Agent: the 12 shipped/wired capabilities plus 5 planned, the three-tier guardrail model, common workflows, the three integration surfaces (REST / MCP / full agent), a consolidated error model, and an evaluation & synthetic-data format grounded in the labelled mailbox corpus. Documents the schema-1.0 contract plus the proposed schema-2.0 taxonomy (#1615). For software-partner integration and test/eval data generation.
Review —
|
Renames the partner-facing spec to specification.html and adds five end-to-end workflows — including a multi-round meeting-time negotiation (propose → counter → re-check → confirm), a search-driven find-and-act, commitment tracking, a prioritization-learning loop, and an attachment-aware reply.
…the full spec Reframes the Evaluation section to specify the dataset a complete test/eval/optimization run needs — required fixture format, must-include coverage, and what a triage-only corpus is missing — rather than describing a specific example corpus. Aligns it with the rest of the spec: schema 2.0 native taxonomy, all 17 capabilities, the 10 workflows, the REST/MCP/agent surfaces, and the error model.
Replaces the prose coverage notes with two concrete fixture shapes — a per-message expected block and a chained scenario fixture (multi-turn, e.g. the W6 scheduling negotiation) — and a coverage matrix mapping all 17 capabilities, P1-P5, and W1-W10 to their fixture type and validating assertion, so the dataset can validate the full agent including chained workflows.
…uarantine (zero-confirm) Workflows W1-W10 are now collapsible, each with a one-line scenario blurb that stays visible when collapsed. Phishing handling moves from confirm-gated quarantine to spam-style auto-quarantine: detected phishing is auto-moved to the quarantine label, the user is notified (no prompt), and can review/unmark a false positive at any time. Updated capabilities 4 and 9, the guardrail tiers (quarantine Tier 2 -> Tier 1), the at-a-glance table, workflows W1/W4, the coverage matrix, and the hard-fail invariants.
…ing, unattended guardrails) New section covering how the email agent runs unattended: time/event/user triggers, the THINK->ACT->SCHEDULE self-scheduling loop, human-readable schedule format with persistence, and the unattended guardrail rule — Tier 0/1 run automatically (auto-quarantine notifies + reverses) while Tier 2 actions queue for approval and never auto-fire. Marked planned (autonomy engine #555). Wired into the nav + coverage matrix.
Why this matters
Software partners integrating the Email Triage Agent — and our own eval engineers — had no single reference for what the agent does, how to call it, and how to generate test data. This adds a self-contained spec covering all 12 shipped/wired capabilities plus 5 planned, the three-tier guardrail model (when the user is asked to approve), ten end-to-end multi-capability workflows, the three integration surfaces (REST / MCP / full agent), a consolidated error model, and an evaluation & synthetic-data format grounded in the labelled mailbox corpus.
It also documents the proposed schema 2.0 taxonomy change — 4-bucket → 5-bucket (
URGENT · NEEDS_RESPONSE · FYI · PROMOTIONAL · PERSONAL) plus asuggested_actionverb, retaining the independentis_spam/is_phishingflags — tracked in #1615. Today's shipped contract (schema 1.0) is clearly marked as current.Notes
hub/agents/python/email/specification.html.Test plan
hub/agents/python/email/specification.htmlin a browser; verify light/dark, collapsible sections, and the in-text endpoint links jump to their reference entries.