Resources

Developer Preview: Plugin authors should assume these resources come from Atomical in the planned preview runtime. Names may change before a stable SDK.

Agent identity

Atomical gives each agent a provider-facing identity. Plugins use that identity instead of creating separate users by default.

• agent.email is used for signup, login, receipts, and provider account mail.
• agent.phone is available when SMS verification is provisioned.
• The provider account should stay tied to this agent identity across setup, recovery, and skills.

Only request another provider identity when the plugin explicitly needs one and Atomical has granted that capability.

Managed browser profile

The browser profile holds the provider account and session context. Setup, recovery, and later skills use the same profile so the provider sees one continuing account.

Plugin code receives an opaque browser handle. Do not launch a separate browser, assume a concrete automation library, or depend on a browser hosting vendor. If the provider logs the agent out, return login_required and let recovery restore the account.

OTP inbox

Atomical routes provider email and SMS codes into the plugin’s OTP inbox. Use email OTP when messages come from a declared sender domain, and SMS OTP when the provider verifies the agent phone number.

const emailCode = await otp.waitForEmailCode({
  service: 'sample-market',
  timeoutMs: 120_000,
});

const smsCode = await otp.waitForSmsCode({
  service: 'sample-market',
  timeoutMs: 120_000,
});

Pass service for SMS when one plugin handles more than one SMS-verifying provider flow. Clear stale messages before a resend when the provider can reuse old subjects or phone numbers. Do not store OTPs in plugin state.

Sender domains

Declare provider sender domains in the manifest so Atomical can route mail to the right plugin inbox.

email: {
  allowedSenderDomains: [
    'sample.example',
    'mail.sample.example',
  ],
}

Matching is exact-domain and subdomain aware:

• sample.example matches sample.example and offers.sample.example.
• mail.sample.example matches links.mail.sample.example.
• sample.example.attacker.net does not match sample.example.

Use the smallest allowlist that covers the provider’s real sender infrastructure.

DoorDash example:

export const doordashEmailDomains = [
  'doordash.com',
  'email.doordash.com',
  'mail.doordash.com',
];

Amazon example:

export const amazonEmailDomains = [
  'amazon.com',
  'email.amazon.com',
  'marketplace.amazon.com',
  'payments.amazon.com',
  'amazonses.com',
];

Managed resources

Managed resources are Atomical-owned objects the plugin can use when declared. The first preview resource is payment_method; later resources may cover addresses, documents, or provider-specific credentials.

if (!resources.paymentMethod) {
  return {
    status: 'failed',
    errorCode: 'missing_resource',
    message: 'A payment method is required before setup can continue.',
  };
}

Read only the resources declared in the manifest. If a required resource is missing, return missing_resource.

State and KV

Plugin state is scoped to the agent, provider, and plugin. Use it for checkpoints the provider would recognize.

{
  "setup": {
    "stage": "active",
    "providerAccountId": "acct_123",
    "updatedAt": "2026-05-15T12:00:00Z"
  }
}

Good state includes stages, provider account IDs, last completed profile steps, and timestamps. Do not store OTPs, raw credentials, full provider responses, or volatile page details.