> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedrock.orinlabs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Adapters

> Understanding Adapters and how to configure them

# Adapters

**Adapters** are integration modules that provide tools to your agents. They define capabilities like sending SMS, managing contacts, or calling external APIs.

## How Adapters Work

* A **Template** attaches **Adapters** through **AdapterConfig** rows, each with:
  * **config** — per-template settings (API keys, phone numbers, etc.)
  * **tools** — callable functions the agent can invoke

1. **Enable adapters** on your template by creating an `AdapterConfig`
2. **Fill in the config** — validated against the adapter's `config_schema`
3. **New agents created from the template** snapshot every `AdapterConfig` into their own `AgentAdapterConfig` row, and inherit the adapter set at runtime

## Built-in Adapters

Bedrock includes these default adapters:

| Adapter                                      | Description                                                                            | Requires Config |
| -------------------------------------------- | -------------------------------------------------------------------------------------- | --------------- |
| **Contacts**                                 | Contact book for storing names, phones, emails                                         | No              |
| **SMS**                                      | Send/receive text messages via Twilio                                                  | Yes             |
| **MMS**                                      | Send/receive iMessage/RCS via Linq                                                     | Yes             |
| **Surge**                                    | Send/receive SMS via Surge                                                             | Yes             |
| **Blooio**                                   | Send/receive iMessage/RCS/SMS via Blooio                                               | Yes             |
| **Email**                                    | Send/receive emails via AgentMail                                                      | Yes             |
| **Gmail**                                    | Read/send from a user's Gmail via OAuth                                                | No (user OAuth) |
| **Google Calendar**                          | Manage events on a user's Google Calendar via OAuth                                    | No (user OAuth) |
| **Google Drive**                             | Browse/read/write a user's Google Drive via OAuth                                      | No (user OAuth) |
| **Strava**                                   | Read a user's activities/training data via OAuth                                       | No (user OAuth) |
| **Slack**                                    | Send messages and receive events from a user's Slack workspace                         | Yes             |
| **Microsoft Teams**                          | Chat in Teams channels/group chats via an Azure Bot (responds when @mentioned)         | Yes             |
| **[Notifications](/concepts/notifications)** | Internal notification/reminder system for agents                                       | No              |
| **Projects**                                 | Hierarchical project tracking with sub-projects                                        | No              |
| **Documents**                                | Store and retrieve text documents                                                      | No              |
| **Computer**                                 | Cloud VM sandbox for shell commands and files                                          | Yes             |
| **Browser**                                  | Asynchronous browser automation for web tasks                                          | Yes             |
| **Exa**                                      | Web search and people/profile search via Exa                                           | Yes             |
| **Sub-Agents**                               | Spawn child agents that run autonomously                                               | No              |
| **Webchat**                                  | Local web-based chat channel for dev / testing (no agent tools; used via the REST API) | No              |

## Adapter Configuration

Some adapters require per-template configuration. For example, SMS needs a Twilio phone number.

### Config Schema

Each adapter defines a `config_schema` (JSON Schema) that specifies required settings:

```json theme={null}
{
  "type": "object",
  "properties": {
    "phone_number": {
      "type": "string",
      "description": "Twilio phone number in E.164 format"
    },
    "twilio_account_sid": {
      "type": "string",
      "description": "Twilio Account SID (optional)"
    },
    "twilio_auth_token": {
      "type": "string",
      "description": "Twilio Auth Token (optional)"
    }
  },
  "required": ["phone_number"]
}
```

### Creating Adapter Config

Attach an adapter to your template:

```bash theme={null}
curl -X POST https://api.bedrock.orinlabs.org/api/toolbox/adapter-configs/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "adapter": "ADAPTER_ID",
    "template": "TEMPLATE_ID",
    "config": {
      "phone_number": "+15551234567"
    }
  }'
```

The config is validated against the adapter's schema. Invalid configs are rejected.

<Note>
  Adapters without required config (Contacts, Projects, Documents, Notifications, Sub-Agents) can still be attached — pass an empty `config: {}`.
</Note>

### SMS Adapter Config

```json theme={null}
{
  "adapter": "sms-adapter-id",
  "template": "your-template-id",
  "config": {
    "phone_number": "+15551234567",
    "twilio_account_sid": "AC...",
    "twilio_auth_token": "..."
  }
}
```

If `twilio_account_sid` and `twilio_auth_token` are omitted, Bedrock uses global environment credentials.

### Email Adapter Config

```json theme={null}
{
  "adapter": "email-adapter-id",
  "template": "your-template-id",
  "config": {
    "agentmail_domain": "yourcompany.agentmail.io",
    "agentmail_api_key": "..."
  }
}
```

### MMS Adapter Config

```json theme={null}
{
  "adapter": "mms-adapter-id",
  "template": "your-template-id",
  "config": {
    "phone_number": "+15551234567",
    "linq_integration_token": "..."
  }
}
```

### Surge Adapter Config

```json theme={null}
{
  "adapter": "surge-adapter-id",
  "template": "your-template-id",
  "config": {
    "phone_number": "+15551234567",
    "surge_api_token": "...",
    "surge_account_id": "..."
  }
}
```

### Computer Adapter Config

```json theme={null}
{
  "adapter": "computer-adapter-id",
  "template": "your-template-id",
  "config": {
    "blaxel_api_key": "..."
  }
}
```

### Browser Adapter Config

```json theme={null}
{
  "adapter": "browser-adapter-id",
  "template": "your-template-id",
  "config": {
    "kernel_api_key": "..."
  }
}
```

### Slack Adapter Config

Slack requires the credentials of a Slack App installed in your Slack workspace.

```json theme={null}
{
  "adapter": "slack-adapter-id",
  "template": "your-template-id",
  "config": {
    "slack_client_id": "...",
    "slack_client_secret": "...",
    "slack_signing_secret": "..."
  }
}
```

### Microsoft Teams Adapter Config

Microsoft Teams is backed by an Azure Bot registration. Every bot points
its messaging endpoint at the single shared URL
`/api/defaults/teams/webhook/` — inbound activities are routed to an agent
by **(bot app id, customer tenant id)**, not by a per-agent URL. Once a
bot is added to a team or group chat, people reach the agent by
@mentioning it; 1:1 chats work without a mention. Each personal chat,
group chat, or channel thread is tracked as its own conversation, and
senders are matched to contacts by their profile email.

Bot credentials live in the **Teams bot registry** (the `TeamsBot` model),
not in the agent's adapter config — a directory-published bot's secret is
shared across many agents. Enabling the adapter on an agent only requires
the (optional) `auto_provision` opt-in:

```json theme={null}
{
  "adapter": "teams-adapter-id",
  "template": "your-template-id",
  "config": {
    "auto_provision": true
  }
}
```

#### Routing model

A bot is identified by the JWT `aud` claim (its Microsoft App ID) and
resolved in the registry. The agent is then chosen by the activity's
customer tenant:

* an explicit **tenant binding** `(bot, tenant_id) -> agent`, or
* the bot's **default agent** when the tenant has no binding.

This supports both multiple distinct bots/agents in one tenant
(disambiguated by app id) and one directory-published bot serving many
customer tenants, each tenant routed to its own agent (disambiguated by
tenant id). Manage bots and bindings via the `teams/bots/` and
`teams/bindings/` endpoints or the Django admin.

#### Auto-provisioning

A template can opt in to auto-provisioning (`"auto_provision": true`).
When an agent is created from such a template, the server automatically
creates a single-tenant Entra app registration, client secret, Azure Bot
resource (F0), and Teams channel, then registers a `TeamsBot` (with the
agent as its default agent) plus a home-tenant binding. Provisioning runs
in the background and typically completes within \~30 seconds; a
notification is recorded on the agent when the bot is ready. This requires
the `TEAMS_PROVISION_*` environment variables to be configured on the
server (tenant, provisioner client ID/secret, subscription, and resource
group).

#### App package

Once an agent has a bot (auto-provisioned or bound in the registry),
download its Teams app package — a zip with the manifest and icons, ready
to sideload or upload to your tenant's app catalog — from the portal's
Teams tab or via:

```bash theme={null}
curl -X GET https://api.bedrock.orinlabs.org/api/defaults/teams/app-package/<agent_id>/ \
  -H "Authorization: Bearer YOUR_API_KEY" -o teams-app.zip
```

The package is keyed to the bot's app id, so a directory-published bot
shared across agents has a single package.

### Exa Adapter Config

```json theme={null}
{
  "adapter": "exa-adapter-id",
  "template": "your-template-id",
  "config": {
    "exa_api_key": "..."
  }
}
```

## Listing Adapters

View all available adapters:

```bash theme={null}
curl -X GET https://api.bedrock.orinlabs.org/api/toolbox/adapters/ \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:

```json theme={null}
[
  {
    "id": "contacts-adapter-id",
    "name": "Contacts",
    "description": "Contact book for managing contacts...",
    "config_schema": {},
    "visibility": "public",
    "tools": ["create_contact", "get_contact", "list_contacts", "update_contact", "delete_contact"]
  },
  {
    "id": "sms-adapter-id",
    "name": "SMS",
    "description": "SMS messaging via Twilio...",
    "config_schema": {...},
    "visibility": "public",
    "tools": ["list_conversations", "get_conversation", "send_sms", "open_attachment"]
  }
]
```

## Adapter Visibility

| Visibility | Description                                         |
| ---------- | --------------------------------------------------- |
| `public`   | Available to all organizations (built-in adapters)  |
| `private`  | Only visible to your organization (custom adapters) |

## Creating Custom Adapters

You can build your own adapters to connect agents to any API or service. Custom adapters use webhooks — when an agent calls your tool, Bedrock POSTs to your URL with the arguments and context.

<Card title="Custom Adapters Guide" icon="webhook" href="/concepts/custom-adapters">
  Full walkthrough: creating an adapter, registering tools, handling webhooks,
  verifying secrets, and best practices.
</Card>

## Attaching Adapters to a Template

Adapters are attached to a template by creating `AdapterConfig` rows — one per adapter — at `/api/toolbox/adapter-configs/` (see [Creating Adapter Config](#creating-adapter-config) above). Removing the `AdapterConfig` row detaches the adapter from the template (but does not affect agents already created from it).

## Agent-Level Adapter Override

By default, agents inherit the adapter set from their template at creation time and own it from then on. You can edit the adapter set on a specific agent:

```bash theme={null}
curl -X PATCH https://api.bedrock.orinlabs.org/api/cloud/agents/AGENT_ID/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "adapters": ["Contacts", "Projects"]
  }'
```

You can use adapter names or UUIDs.