From c6ddeb3b80bc80c795f474eeb2f355639f1a82ba Mon Sep 17 00:00:00 2001 From: airplanestar888 Date: Sat, 4 Jul 2026 03:05:53 +0000 Subject: [PATCH] =?UTF-8?q?Showcase:=20Agent=20Email=20OTP=20=E2=80=94=20A?= =?UTF-8?q?utomated=20Inbox=20&=20Verification?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add agent-email-otp showcase package - Reusable skill for ACP agent email: whoami, compose, inbox, extract-otp, thread, search, reply, extract-links, attachment - Primitives: Agent Email + Agent Wallet - Zero funding required — works with any ACP agent out of the box - Includes: showcase.json, SKILL.md, result-redacted.md, prompt.md, README.md - All sensitive data redacted per Showcase contribution rules --- showcase/agent-email-otp/README.md | 55 ++++++ showcase/agent-email-otp/prompt.md | 28 +++ showcase/agent-email-otp/result-redacted.md | 121 +++++++++++++ showcase/agent-email-otp/showcase.json | 58 ++++++ .../skills/agent-email-otp/SKILL.md | 171 ++++++++++++++++++ 5 files changed, 433 insertions(+) create mode 100644 showcase/agent-email-otp/README.md create mode 100644 showcase/agent-email-otp/prompt.md create mode 100644 showcase/agent-email-otp/result-redacted.md create mode 100644 showcase/agent-email-otp/showcase.json create mode 100644 showcase/agent-email-otp/skills/agent-email-otp/SKILL.md diff --git a/showcase/agent-email-otp/README.md b/showcase/agent-email-otp/README.md new file mode 100644 index 0000000..cfaf1cf --- /dev/null +++ b/showcase/agent-email-otp/README.md @@ -0,0 +1,55 @@ +# Agent Email OTP — Automated Inbox & Verification + +## What It Does + +An EconomyOS agent uses its built-in email identity to: +- Receive emails autonomously +- Extract OTP/verification codes from email bodies +- Read and reply to email threads +- Complete email-based identity verification flows + +## Why It Matters + +Email verification is a core primitive for agent autonomy. Whether signing up for services, completing checkout flows, or verifying identity — agents need to read inbox, extract codes, and act on email content without human intervention. + +## EconomyOS Primitives + +- **Agent Email** — provisioned identity, inbox, compose, thread, OTP extraction +- **Agent Wallet** — underlying identity layer + +## Zero Funding Required + +Unlike trading or marketplace demos, this workflow needs **no USDC, no wallet topup, and no on-chain transactions**. Any ACP agent with a provisioned email can run this flow immediately after creation. + +## Skill + +The reusable skill is located at `skills/agent-email-otp/SKILL.md`. It covers: + +1. Email identity verification +2. Email composition (send) +3. Inbox reading +4. OTP extraction +5. Thread reading +6. Email search +7. Email reply +8. Link extraction +9. Attachment download + +## Files + +``` +showcase/agent-email-otp/ + showcase.json # Showcase metadata + prompt.md # Demo prompt + result-redacted.md # Redacted proof report + skills/ + agent-email-otp/ + SKILL.md # Reusable skill documentation + references/ # Reference materials +``` + +## Install Skill + +```bash +cp -R showcase/agent-email-otp/skills/agent-email-otp ~/.agents/skills/ +``` diff --git a/showcase/agent-email-otp/prompt.md b/showcase/agent-email-otp/prompt.md new file mode 100644 index 0000000..b21efdc --- /dev/null +++ b/showcase/agent-email-otp/prompt.md @@ -0,0 +1,28 @@ +# Demo Prompt — Agent Email OTP + +## Prompt + +You are an ACP agent with a provisioned email identity. Demonstrate the full email workflow: + +1. Verify your email identity is active (`acp email whoami`) +2. Send a test email to yourself containing a 6-digit OTP code (`acp email compose`) +3. Read your inbox and confirm the email arrived (`acp email inbox --json`) +4. Extract the OTP code from the received email (`acp email extract-otp`) +5. Read the full thread to view the complete email body (`acp email thread`) + +Document each step with the command, output, and result. Produce a redacted report suitable for public sharing. + +## Expected Output + +- Email identity verification (active) +- Successful email send (Message ID returned) +- Inbox with received message(s) +- Extracted OTP code +- Full thread body +- Redacted result report + +## Notes + +- This demo requires zero funding — email is provisioned with the agent identity +- The agent sends email to itself for self-testing (loopback) +- All sensitive data (OTP, email address, IDs) must be redacted in the final report diff --git a/showcase/agent-email-otp/result-redacted.md b/showcase/agent-email-otp/result-redacted.md new file mode 100644 index 0000000..5d83cca --- /dev/null +++ b/showcase/agent-email-otp/result-redacted.md @@ -0,0 +1,121 @@ +# Agent Email OTP — Redacted Result Report + +## Overview + +This report documents a successful end-to-end test of the Agent Email OTP workflow using the ACP CLI. Sensitive data has been redacted per Showcase contribution rules. + +## Test Environment + +- **Agent**: airplane (ACP agent, HYBRID role) +- **Agent ID**: `019f0a02-50d4-7169-b047-a5771369e32a` +- **Email**: `j***@agents.world` (redacted) +- **ACP CLI Version**: 1.0.22 +- **Date**: 2026-07-04 +- **Wallet**: `0x3282******************************` (redacted) + +## Flow Steps & Results + +### Step 1: Verify Email Identity + +```bash +acp email whoami +``` + +**Result**: ✅ Active + +| Field | Value | +|-------|-------| +| Agent ID | `019f0a02-50d4-7169-b047-a5771369e32a` | +| Email | `j***@agents.world` | +| Status | `active` | +| Created | 2026-06-27 | + +### Step 2: Send Test Email (Self-Test) + +```bash +acp email compose \ + --to "j***@agents.world" \ + --subject "Test OTP - Agent Email Showcase" \ + --body "Your verification code is: [REDACTED]" +``` + +**Result**: ✅ Email sent + +| Field | Value | +|-------|-------| +| Message ID | `[REDACTED]` | +| Thread ID | `[REDACTED]` | + +### Step 3: Read Inbox + +```bash +acp email inbox --json +``` + +**Result**: ✅ 2 messages found (1 inbound, 1 outbound) + +| Direction | Subject | Status | +|-----------|---------|--------| +| inbound | Test OTP - Agent Email Showcase | unread | +| outbound | Test OTP - Agent Email Showcase | read | + +### Step 4: Extract OTP + +```bash +acp email extract-otp --message-id "[REDACTED]" --json +``` + +**Result**: ✅ OTP extracted successfully + +```json +{ + "code": "[REDACTED]", + "allCodes": ["[REDACTED]"] +} +``` + +The CLI successfully detected the 6-digit OTP code from the email body. + +### Step 5: Read Full Thread + +```bash +acp email thread --thread-id "[REDACTED]" --json +``` + +**Result**: ✅ Full thread retrieved + +- Thread contained 1 message (inbound) +- Complete body text available (`textBody`) +- HTML body was empty (plain text email) +- No attachments + +## Validation Checklist + +- [x] `acp email whoami` returns active status +- [x] `acp email compose` successfully sends (returns Message ID) +- [x] `acp email inbox --json` returns received messages +- [x] `acp email extract-otp --message-id --json` returns OTP code +- [x] `acp email thread --thread-id --json` returns full thread +- [x] All proof artifacts are redacted of sensitive data + +## Primitives Used + +1. **Agent Email** — identity, inbox, compose, thread, OTP extraction +2. **Agent Wallet** — identity signing (implicit, email provisioned via agent wallet) + +## Key Findings + +- ACP CLI email commands work end-to-end out of the box with zero funding +- OTP extraction successfully parsed a 6-digit numeric code from plain text email +- Inbox polling returns both inbound and outbound messages +- Thread API returns complete body text for audit/logging +- Email delivery latency: ~4 seconds (send to inbox visibility) + +## Redaction Notes + +The following items were redacted from this report: +- Full agent email address +- OTP code value +- Message IDs and Thread IDs +- Full wallet address +- All API tokens and credentials diff --git a/showcase/agent-email-otp/showcase.json b/showcase/agent-email-otp/showcase.json new file mode 100644 index 0000000..0174466 --- /dev/null +++ b/showcase/agent-email-otp/showcase.json @@ -0,0 +1,58 @@ +{ + "slug": "agent-email-otp", + "title": "Agent Email OTP — Automated Inbox & Verification", + "tagline": "An ACP agent reads its own inbox, extracts OTP codes, and completes email-based verification flows autonomously.", + "description": "This demo showcases a reusable workflow where an EconomyOS agent uses its built-in email identity to receive messages, extract one-time passwords, read threads, and complete verification flows. The skill covers the full lifecycle: verify email identity, send test email, read inbox, extract OTP, read thread, search, reply, and extract links. Zero funding required — works with any ACP agent out of the box.", + "status": "validated demo", + "topic": "identity", + "topics": ["identity", "email", "automation"], + "hidden": false, + "builder": { + "name": "airplane", + "url": "https://os.virtuals.io" + }, + "links": { + "repo": "https://github.com/Virtual-Protocol/acp-cli-demos", + "demo": "https://github.com/Virtual-Protocol/acp-cli-demos/tree/main/showcase/agent-email-otp", + "feedback": "https://github.com/Virtual-Protocol/acp-cli-demos/issues" + }, + "primitives": ["email", "wallet"], + "visual": { + "kind": "console demo", + "eyebrow": "acp-cli", + "title": "Agent Email OTP Flow", + "posterUrl": "", + "videoLabel": "" + }, + "skills": [ + { + "name": "agent-email-otp", + "href": "https://github.com/Virtual-Protocol/acp-cli-demos/tree/main/showcase/agent-email-otp/skills/agent-email-otp", + "sourcePath": "showcase/agent-email-otp/skills/agent-email-otp", + "summary": "Reusable workflow for ACP agent email: verify identity, send emails, read inbox, extract OTP codes, read threads, search, reply, and extract links. Zero funding required.", + "install": "cp -R showcase/agent-email-otp/skills/agent-email-otp ~/.agents/skills/" + } + ], + "artifacts": [ + { + "label": "Redacted result report", + "href": "https://github.com/Virtual-Protocol/acp-cli-demos/blob/main/showcase/agent-email-otp/result-redacted.md", + "kind": "proof" + }, + { + "label": "Demo prompt", + "href": "https://github.com/Virtual-Protocol/acp-cli-demos/blob/main/showcase/agent-email-otp/prompt.md", + "kind": "prompt" + }, + { + "label": "Skill source", + "href": "https://github.com/Virtual-Protocol/acp-cli-demos/tree/main/showcase/agent-email-otp/skills/agent-email-otp", + "kind": "skill" + } + ], + "feedbackPrompts": [ + "Could this skill support real-time OTP push notifications instead of polling?", + "What other email-based verification flows should this skill cover?", + "How could this integrate with agent card checkout flows for end-to-end signup?" + ] +} diff --git a/showcase/agent-email-otp/skills/agent-email-otp/SKILL.md b/showcase/agent-email-otp/skills/agent-email-otp/SKILL.md new file mode 100644 index 0000000..ee77278 --- /dev/null +++ b/showcase/agent-email-otp/skills/agent-email-otp/SKILL.md @@ -0,0 +1,171 @@ +# Agent Email OTP — Automated Inbox & OTP Extraction + +## When to Use + +- An agent needs to receive emails and extract OTP/verification codes automatically +- An agent needs to read its inbox, parse threads, and act on email content +- An agent needs to send emails (notifications, confirmations, test messages) +- An agent needs to complete email-based identity verification flows + +## When NOT to Use + +- You need real-time push notifications (this is poll-based) +- The email provider is not supported by ACP CLI +- You need to process attachments in binary formats not handled by the CLI + +## Required Inputs + +- **ACP CLI** installed and configured (`acp configure`) +- **Active ACP agent** with a provisioned email identity (`acp email whoami`) +- **Agent email address** — automatically provisioned via `acp agent create` or `acp email provision` + +## Preconditions + +1. Verify email identity is active: + ```bash + acp email whoami + ``` +2. Confirm the agent wallet is set: + ```bash + acp wallet address + ``` + +## Step-by-Step Workflow + +### Step 1: Verify Email Identity + +```bash +acp email whoami +``` + +Confirm the agent has an active email address. If not provisioned: + +```bash +acp email provision +``` + +### Step 2: Send a Test Email (Optional — for Self-Testing) + +```bash +acp email compose \ + --to "" \ + --subject "Test OTP - Verification" \ + --body "Your verification code is: 123456" +``` + +Capture the `Message ID` and `Thread ID` from the output. + +### Step 3: Read Inbox + +```bash +acp email inbox --json +``` + +Parse the JSON response to find inbound messages. Key fields: +- `id` — message ID (used for OTP extraction) +- `threadId` — thread ID (used for thread reading) +- `direction` — `inbound` or `outbound` +- `bodyPreview` — first few lines of the email body +- `receivedAt` — timestamp + +### Step 4: Extract OTP Code + +```bash +acp email extract-otp --message-id "" --json +``` + +Returns: +```json +{ + "code": "849273", + "allCodes": ["849273"] +} +``` + +The CLI scans the email body for common OTP patterns (4-8 digit codes, alphanumeric codes) and returns them. + +### Step 5: Read Full Thread (Optional) + +```bash +acp email thread --thread-id "" --json +``` + +Returns the full thread with all messages, including complete body text (`textBody`, `htmlBody`). + +### Step 6: Search Inbox (Optional) + +```bash +acp email search --query "verification" --json +``` + +Search across subject and body for specific keywords. + +### Step 7: Reply to Thread (Optional) + +```bash +acp email reply --thread-id "" --body "Verification complete." +``` + +### Step 8: Extract Links (Optional) + +```bash +acp email extract-links --message-id "" --json +``` + +Extracts all URLs from an email body — useful for magic-link login flows. + +### Step 9: Download Attachment (Optional) + +```bash +acp email attachment --message-id "" --filename "document.pdf" --output "./downloads" +``` + +## Approval Gates + +- **Email compose** — sends an email from the agent's identity. Ensure recipients are intentional. +- **OTP extraction** — read-only, no approval needed. +- **Email reply** — sends a reply. Ensure content is appropriate. + +## Stop Conditions + +- Email identity not provisioned → run `acp email provision` first +- Inbox empty → no messages to process; wait or trigger a new email +- OTP not found in email → the email may not contain a recognizable code pattern; fall back to `acp email thread` and parse manually + +## Evidence and Redaction Rules + +When producing proof for Showcase or external sharing: + +- **NEVER** expose the full agent email address in public reports if it is sensitive (redact to `j***@agents.world`) +- **NEVER** share OTP codes in public reports — replace with `[REDACTED]` +- **NEVER** share email thread IDs or message IDs that could allow inbox enumeration +- **NEVER** share API keys, auth tokens, or session cookies +- **DO** show command structure, flow steps, and success/failure states +- **DO** redact sensitive fields while keeping the workflow visible + +## Validation Checklist + +- [ ] `acp email whoami` returns active status +- [ ] `acp email compose` successfully sends (returns Message ID) +- [ ] `acp email inbox --json` returns received messages +- [ ] `acp email extract-otp --message-id --json` returns OTP code +- [ ] `acp email thread --thread-id --json` returns full thread +- [ ] All proof artifacts are redacted of sensitive data + +## Output Contract + +After running this skill, the agent produces: + +1. **OTP code** — extracted verification code (string) +2. **Thread data** — full email thread JSON (for audit/logging) +3. **Inbox snapshot** — current inbox state (for debugging) +4. **Redacted report** — markdown report of the flow with sensitive data removed + +## Error Codes + +| Error | Cause | Fix | +|-------|-------|-----| +| `email not provisioned` | Agent has no email identity | Run `acp email provision` | +| `inbox empty` | No messages received | Wait for email or send a test | +| `otp not found` | No OTP pattern in email | Check email body via `acp email thread` | +| `message not found` | Invalid message ID | Re-check `acp email inbox` for valid IDs |