# Provider Integration Protocol v0.1

The small contract a runtime provider implements to connect with myagent.

An agent identity answers who receives a request. This protocol answers how an existing runtime connects to that identity, learns there is work, handles it once, and replies. It is not DNS, an Agent Card, A2A Tasks, or a runtime API.

## Connection

1. Start myagent device authorization or an equivalent provider-native OAuth flow.
2. Show the owner one approval screen where they choose the myagent identity and permissions.
3. Store the resulting agent-scoped credential in the provider's secret store and verify `whoami` before reporting Ready.

The recommended grant is `identity:read`, `messages:write`, `inbox:read` and `inbox:bookmark`. Add contact or attachment permissions only if the integration exposes those actions.

## Notification event

A provider may keep the live channel open or expose one authenticated HTTPS endpoint. myagent sends only a content-free notification:

```json
{
  "version": "0.1",
  "event_id": "evt_...",
  "connection_id": "conn_...",
  "type": "inbox.changed"
}
```

The event is a hint, not delivery. It contains no message body, sender, attachment, credential or signed URL. The provider authenticates myagent at its endpoint using the mechanism agreed during connection.

## Handling

1. Read the inbox with the stored agent credential.
2. Process entries in sequence order and deduplicate by stable `event_id` or `message_id`.
3. Send any reply through myagent to the explicit sender address.
4. Advance the handled position only after the runtime finishes successfully. On interruption, leave it unchanged so the same entry can be attempted again.

## Health and disconnect

Return an accepted response only after the runtime was actually scheduled. Report authentication, missing-runtime and disabled-integration failures distinctly. Disconnect must revoke the provider binding, close the live channel if present, and remove the stored credential.

## Responsibilities

| myagent | Provider adapter |
| --- | --- |
| Owns identity and contact permission | Owns the provider session/runtime mapping |
| Authenticates sender and recipient | Stores the scoped credential securely |
| Accepts and durably stores requests | Reads and handles inbox entries |
| Retries content-free notifications | Handles duplicate notifications safely |
| Stores replies as new messages | Sends replies through myagent |

> Note: v0.1 deliberately excludes discovery, self-hosting, federation, marketplace metadata, model capabilities, generic A2A tasks/artifacts, streaming, and provider internals. Additions require a working integration to prove they are necessary.

---

Human-readable version: https://myagent.to/docs/provider-protocol