Extensions

Extensions let your agent call external APIs, other agents, human contacts, and local tools during conversations. When a user's request requires an external service, the agent calls the appropriate extension and uses the result.

How they work

1. You register an extension in extensions/registry.json (or through the dashboard)
2. The agent automatically gets a tool it can call during conversations
3. When a user's request requires the extension, the agent calls it and incorporates the result into its response

Registering an extension

{
  "extensions": [
    {
      "name": "weather",
      "description": "Get current weather conditions for a city",
      "type": "api",
      "endpoint": "https://api.weather.com/v1/current",
      "auth": {
        "type": "bearer",
        "apiKey": "YOUR_API_KEY"
      },
      "capabilities": ["current_weather", "forecast"],
      "cost_model": "free"
    }
  ]
}

Auth types

The extension system supports four authentication methods:

Bearer	Sends Authorization: Bearer YOUR_KEY header. The default if no type is specified.
Custom Header	Sends the key in a custom header (e.g. X-API-Key). Set type: "header" and header: "X-API-Key".
Query Parameter	Appends the key to the URL (e.g. ?key=YOUR_KEY). Set type: "query".
Basic Auth	Base64-encoded username:password. Set type: "basic" and apiKey: "user:pass".

You can also add arbitrary custom headers via the headers object on any extension.

Extension types

API	External REST APIs (Stripe, weather services, shipping, email, etc.)
Agent	Other AaaS agents. The agent can delegate sub-tasks to them.
Human	Human contacts the agent can escalate to when it needs help.
Tool	Local commands and scripts on the host machine.

Payment flow

When your service involves payments through an external provider (Stripe, PayPal, etc.), the agent follows this pattern:

1. Creates a payment link via the extension
2. Sends the link to the user and asks them to confirm when they have paid
3. Saves the payment session ID to memory
4. When the user confirms, verifies the payment status via the extension
5. If confirmed, proceeds with the service. If not, tells the user the payment was not found.

This approach does not require webhooks or a public URL. The agent verifies payment status on demand by calling the payment provider's API.

Managing extensions

You can manage extensions through:

• The Extensions page in the dashboard (visual form with auth configuration and test button)
• The CLI: aaas extensions add --name weather --type api --endpoint URL
• Editing extensions/registry.json directly

Referencing in your skill

Tell the agent about its extensions in the SKILL.md so it knows when to use them:

## Extensions Available

- **weather** -- Check weather before recommending travel dates
- **send_email** -- Send order confirmations and shipping notifications
- **calculate_shipping** -- Get real-time shipping rates for purchases