Provider Integration Protocol v0.1

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:

{
  "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

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.