Skip to content

llms-agent-guide.md

Latest commit

 

History

History
226 lines (177 loc) · 7.31 KB

llms-agent-guide.md

File metadata and controls

226 lines (177 loc) · 7.31 KB

LLM Agent Guide

This is the single best starting point for an LLM agent or agent-platform developer integrating with the Mailagents Email Runtime.

If you only read one page first, read this one.

What This Runtime Is

Mailagents is an email-first AI agent runtime built on:

  • Cloudflare Workers
  • Cloudflare Email Routing
  • Cloudflare Queues
  • Cloudflare R2
  • Cloudflare D1
  • Amazon SES

It provides:

  • inbound email ingestion and normalization
  • tenant-scoped agent and mailbox access
  • mailbox-scoped high-level send and reply surfaces for common agent workflows
  • drafts as the lower-level control point for outbound side effects
  • asynchronous outbound delivery through SES
  • MCP tools and composite workflows for agent orchestration

The Fastest Safe Mental Model

Think in this order:

  1. discover capabilities
  2. obtain a least-privilege bearer token
  3. read state before side effects
  4. prefer mailbox-scoped high-level send and reply surfaces
  5. use explicit idempotencyKey values for retryable side effects
  6. branch only on stable error codes

Start Here

Read these in order:

  1. docs/ai-onboarding.md
  2. docs/ai-auth.md
  3. docs/runtime-metadata.md
  4. docs/runtime-compatibility.md
  5. docs/agent-sdk-examples.md
  6. docs/agent-client-helper.md

Use these as deeper references:

Capability Discovery

Three discovery layers are available:

  1. runtime metadata Path: /v2/meta/runtime Use for richer environment-aware discovery.
  2. compatibility contract Path: /v2/meta/compatibility Use for stable agent branching logic and long-lived integrations.
  3. compatibility schema Path: /v2/meta/compatibility/schema Use for CI validation, SDK fixtures, and contract snapshot testing.
  4. agent capabilities example fixture Path: docs/agent-capabilities.json Use as a repository-pinned admin-enabled example response and integration fixture.

Current shared dev URLs:

Authentication

Default integration auth is a signed bearer token.

For mailboxes created through the signup API, the first bearer token is returned inline by default from POST /public/signup. The same token may also be delivered through the configured operator channel. Runtimes can explicitly disable inline return if they want operator-channel-only bootstrap.

If that signup API token later expires, recovery should use POST /public/token/reissue. That endpoint only emails a refreshed token to the original operatorEmail from signup and does not return the token inline.

If the signup API token is still valid and the agent wants to rotate it without emailing the operator, use POST /v1/auth/token/rotate. That authenticated route can return the rotated token inline, deliver it back to the mailbox itself, or both.

Minimum common scopes by job:

  • read-only mail agent
    • mail:read
    • task:read
  • reply-capable mail agent
    • mail:read
    • task:read
    • draft:create
    • draft:read
    • draft:send
  • provisioning agent
    • agent:create
    • agent:update
    • agent:bind
  • recovery operator
    • mail:replay

Use:

  • short expirations
  • mailbox-scoped tokens when possible
  • the narrowest scope set that still completes the workflow

Core Safe Rules

  • prefer reads before writes
  • prefer list_messages, send_email, and reply_to_message for mailbox-scoped agents
  • treat high-level send and reply calls as draft-backed side effects
  • treat send_draft as the lower-level delivery primitive when the workflow needs explicit draft control
  • treat replay as recovery, not as implicit permission to send
  • keep admin and debug routes out of normal agent workflows
  • reuse the same idempotencyKey when retrying the same logical send or replay

Best MCP Entry Points

Primitive tools:

  • list_messages
  • get_message
  • get_message_content
  • get_thread
  • create_draft
  • get_draft
  • send_draft
  • replay_message

Composite tools:

  • send_email
  • reply_to_message
  • reply_to_inbound_email
  • operator_manual_send

When planning from tools/list, always inspect:

  • riskLevel
  • sideEffecting
  • humanReviewRequired
  • supportsPartialAuthorization
  • sendAdditionalScopes

Stable Error Handling

Do not branch on free-form error text.

Branch on stable MCP error codes from the compatibility contract, such as:

  • auth_unauthorized
  • auth_missing_scope
  • access_mailbox_denied
  • resource_message_not_found
  • resource_draft_not_found
  • idempotency_conflict
  • idempotency_in_progress

Suggested behavior:

  • auth_missing_scope Stop and request broader authorization.
  • access_mailbox_denied Stop and request mailbox approval or a different token.
  • resource_*_not_found Refresh identifiers or upstream state.
  • idempotency_in_progress Retry after a short delay.
  • idempotency_conflict Treat as a different logical request unless caller reuse is intentional.

Best Next Document By Need

If you are trying to:

Recommended External-Agent Startup Sequence

  1. read /v2/meta/compatibility
  2. validate against /v2/meta/compatibility/schema
  3. obtain a mailbox-scoped token, usually via the configured operator delivery path triggered by POST /public/signup
  4. call tools/list
  5. filter out tools that require human review when automation is not allowed
  6. prefer read tools first
  7. use list_messages to inspect mailbox state
  8. use send_email and reply_to_message for the common mailbox workflow
  9. drop down to create_draft and send_draft only when explicit draft control is required
  10. use idempotencyKey on side-effecting retries
  11. record the compatibility version you integrated against