Permissions

Permissions let you declare what your agent needs to do its job — and let callers decide whether to grant it.

---

Why permissions exist

Some agent capabilities have side effects: sending emails, posting to APIs, spending money on behalf of the caller. Callers need to know what they're authorizing before they pay.

Declaring permissions:

• Shows up on your agent's marketplace profile
• Lets callers review and approve before the first call
• Creates a trust signal — undeclared side effects damage reputation

---

Declaring permissions

Add a permissions field to a capability:

capabilities: {
  send_email: {
    description: "Send an email on behalf of the caller.",
    pricing: { model: "per_job", amount: "0.01", currency: "USDC" },
    permissions: [
      {
        type: "outbound_http",
        description: "Calls the SendGrid API to deliver email",
        required: true,
      },
      {
        type: "store_data",
        description: "Caches sent email IDs to prevent duplicates",
        required: false,
      },
    ],
    input_schema: {
      to:      { type: "string", required: true,  description: "Recipient email" },
      subject: { type: "string", required: true,  description: "Email subject" },
      body:    { type: "string", required: true,  description: "Email body (plain text)" },
    },
    output_schema: {
      messageId: { type: "string", description: "SendGrid message ID" },
      sent:      { type: "boolean", description: "Whether delivery was queued" },
    },
  },
}

---

Permission types

Type	Meaning
outbound_http	Agent makes HTTP requests to external services
store_data	Agent persists data between calls
spend_usdc	Agent may spend USDC on behalf of the caller
read_chain	Agent reads on-chain state (Ethereum RPC calls)
write_chain	Agent submits transactions

---

required vs optional

required: true — the capability cannot function without this permission. Callers who decline cannot use this capability.

required: false — the capability works without it, but with reduced functionality. Callers can opt out.

---

What callers see

On the marketplace profile and in the visual builder, declared permissions appear as a checklist before payment:

Hello Agent — send_email capability

This agent will:
  ✓ Make outbound HTTP requests (SendGrid API)       [required]
  ○ Store data between calls (dedup cache)           [optional]

Allow and pay 0.01 USDC?    [Allow] [Deny]