{
  "schemaVersion": "1.0",
  "title": "Profiles, transports, and connectors",
  "description": "Use this page to choose the correct integration boundary without creating a second action model or bypassing AIP governance. It is for application, gateway, and connector developers who need to distinguish protocol semantics, wire delivery,",
  "canonical": "https://getaip.org/docs/concepts/profiles-and-connectors",
  "route": "/docs/concepts/profiles-and-connectors",
  "source": "docs/concepts/profiles-and-connectors.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Core Concepts",
  "documentType": "Concept",
  "language": "en",
  "revision": {
    "lastReviewedRevision": "97be86e9efedf07ecf1783b03800f683f107fb04",
    "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb",
    "basis": "frontmatter"
  },
  "downloads": {
    "md": "/docs/download/concepts/profiles-and-connectors.md",
    "txt": "/docs/download/concepts/profiles-and-connectors.txt",
    "json": "/docs/download/concepts/profiles-and-connectors.json",
    "pdf": "/docs/download/concepts/profiles-and-connectors.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Profiles, transports, and connectors\ndescription: Keep AIP semantics, wire bindings, protocol mappings, product adapters, and process placement separate\nkind: explanation\naudience: developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\n---\n\n# Profiles, transports, and connectors\n\nUse this page to choose the correct integration boundary without creating a\nsecond action model or bypassing AIP governance. It is for application,\ngateway, and connector developers who need to distinguish protocol semantics,\nwire delivery, compatibility mapping, product behavior, and process placement.\n\nAIP has one native semantic model. A transport moves that model, a\ncompatibility profile projects another protocol onto it, and a connector maps\nan AIP capability to a product. A connector can run inside a trusted process or\nbehind a separately deployed connector host. Placement changes the trust and\nfailure boundary, but it does not change the meaning of the action.\n\nThis page describes the reviewed Rust implementation of AIP 1.0 at source\nrevision `97be86e9efedf07ecf1783b03800f683f107fb04`. It explains architecture,\nnot production qualification. The maintained public connector set in this\ndocumentation is Cal.diy, Hermes Agent, Chatwoot, Dify, CrewAI, and Twenty.\n\n## Keep four integration layers separate\n\nThe layers compose, but none substitutes for another.\n\n| Layer | Question it answers | What it owns | What it does not own |\n|---|---|---|---|\n| AIP semantics | What work is requested, governed, and observed? | Envelopes, actions, capabilities, identity claims, lifecycle, approvals, transactions, errors, and evidence | A provider API or network connection |\n| Transport binding | How does a native AIP envelope move between peers? | Framing, encoding, connection behavior, delivery metadata, and transport errors | Capability authorization or provider behavior |\n| Compatibility profile | How does another protocol project onto AIP? | Foreign data-transfer objects (DTOs), deterministic mappings, method and error projection, and compatibility metadata | A parallel action store or product credentials |\n| Product connector | How does a product perform the requested capability? | Provider DTOs, authentication at the provider edge, invocation, error normalization, and supported recovery behavior | Global identity, policy, approval, or action lifecycle |\n\nProcess placement is a separate decision. The same product connector contract\ncan be registered as a trusted local handler or hosted behind the connector\nfleet boundary. Treating placement as a fifth protocol layer would confuse a\ndeployment choice with wire semantics.\n\n## A profile identifier is a declaration\n\n`ProfileId` is a general namespace used across discovery and bindings. A\nparticipant manifest advertises supported profile identifiers. A manifest\nrequest and its filter can select them, and an individual capability binding\ncan attach profile-specific metadata.\n\nThe namespace is broader than “compatibility protocol.” The reviewed source\nuses profile identifiers for all of these purposes:\n\n- native transport bindings, such as `aip.native.nats.v1`;\n- streaming bindings, such as `aip.sse.stream.v1` and\n  `aip.websocket.stream.v1`;\n- compatibility mappings, such as `aip.mcp.compat.v1` and\n  `aip.a2a.compat.v1`;\n- the generic signed-webhook contract `aip.http.webhook.v1`;\n- connector-specific capability bindings.\n\nAn advertised identifier says that the publisher declares compatibility with\nthat namespace. It does not prove that an endpoint is reachable, a route has\nbeen admitted, the peer is authenticated, the caller is authorized, or a live\nreplica is ready. Those checks belong to transport, identity, registry, and\nruntime boundaries.\n\n## Native transports preserve the envelope\n\nThe shared transport abstraction carries a native `Envelope` with normalized\nmetadata. Request/reply and streaming behavior are separate traits, so a\ntransport implementation does not imply support for every interaction pattern.\n\n| Binding | Native behavior in the reviewed source | Appropriate use |\n|---|---|---|\n| HTTP | Encodes an envelope as JSON with `application/aip+json`; recommends message, action, and manifest paths; maps protocol error categories to HTTP status classes | Common service ingress and request/reply |\n| NATS | Publishes or requests native envelopes on structured AIP subjects, with optional queue groups and correlation streams | Brokered service routing and workers |\n| SSE | Encodes native envelopes as one-way events, preserves event identifiers for reconnection, and marks results, errors, and final chunks as terminal | Following events or streamed output over HTTP |\n| WebSocket | Encodes envelopes as text frames and provides session queues, correlation subscriptions, ping/pong, and close behavior | Authenticated bidirectional multiplexing |\n\nChanging the binding does not change an action ID, capability contract,\nidentity rules, approval state, transaction state, or result meaning. Transport\nauthentication also does not grant capability authority. The gateway must\nstill establish a trusted actor and apply policy before execution.\n\nThe transport crates provide reusable framing and state. A concrete server\nmust still expose routes, authenticate connections, apply limits, and connect\nframes to the gateway. The product-neutral daemon supplies those server\nboundaries for its configured HTTP, SSE, WebSocket, and NATS surfaces.\n\n## Compatibility profiles translate at the edge\n\nA compatibility profile lets a client use an established protocol while AIP\nremains the internal semantic and lifecycle authority.\n\nThe MCP profile owns MCP DTOs and deterministic mappings between tool,\nresource, task, progress, error, and AIP concepts. It deliberately contains no\nHTTP server, subprocess, or runtime state. Those responsibilities stay in the\nMCP server, client, and transport components.\n\nThe A2A profile similarly maps Agent Cards, messages, tasks, status updates,\nstreaming, cancellation, and push-notification concepts. The signed-webhook\nprofile is narrower: it defines normalized webhook headers and verifies an\nHMAC-SHA256 signature with a timestamp-skew boundary. A product connector still\nhas to interpret the verified provider event.\n\nA profile adapter should therefore perform three bounded steps:\n\n1. validate the foreign request under that protocol's rules;\n2. create or address the corresponding native AIP operation;\n3. project the native result, status, stream, resource, or error back to the\n   foreign protocol.\n\nThe native action remains authoritative throughout the second step. A profile\nmust not create a separate approval engine, transaction store, or connector\ncredential path merely because the foreign protocol names those concepts\ndifferently.\n\n## A connector implements product behavior\n\nThe base connector contract identifies a connector, discovers its manifest,\nmaps failures, and reports health. Additional traits make supported behavior\nexplicit: capability discovery, outbound invocation, channel ingress and\negress, external-event ingestion, escalation, and typed transaction or recovery\noperations.\n\nThe production typed boundary, `FrozenConnector`, receives a complete trusted\nexecution context. It can implement normal invocation, planning, commit,\ncompensation, cancellation, reconciliation, emission, and ingestion. Every\noptional operation fails as unsupported unless the connector overrides it.\nThat default prevents an advertised capability from silently acquiring safety\nproperties that its provider does not implement.\n\nA product connector owns only its product edge. Typical responsibilities are:\n\n- converting a capability input into provider requests;\n- loading credential material from connector-owned process storage;\n- pinning the correct provider account from trusted execution context;\n- normalizing provider responses and failures into AIP results;\n- retaining provider operation references needed for reconciliation;\n- verifying product webhooks before mapping them to AIP envelopes;\n- declaring implementation support that matches the admitted artifact.\n\nThe connector does not trust caller-supplied tenant or credential values. It\nalso does not decide the global approval policy, rewrite the AIP lifecycle, or\nprove its own qualification merely by publishing a manifest.\n\n## Choose local or remote placement deliberately\n\nThe reviewed implementation supports two materially different placements.\n\n| Placement | Execution path | Trust and operations boundary |\n|---|---|---|\n| Trusted local module | The gateway discovers the connector manifest, admits callable capabilities with local handlers, and invokes the connector with runtime-established context | Connector code, credentials, failures, and resource use share the gateway process boundary |\n| Remote connector fleet | The central runtime resolves a tenant-scoped route, sends a signed native AIP action to a registered host, and verifies the signed response | Provider credentials and connector code stay in a separately leased, observable, and drainable host process |\n\nThe typed local path wraps each admitted non-resource capability in a handler.\nThe handler rejects calls without trusted execution context and selects the\nconnector operation from the action transaction mode. Local placement reduces\nnetwork and control-plane machinery, but it also increases the blast radius of\nconnector faults and may place provider secrets in the central process.\n\nThe remote path adds registry, route, identity, lease, capacity, and callback\nboundaries. That machinery supports independent rollout and isolation, but it\nalso requires durable control-plane state and another authenticated hop. Remote\nplacement is not inherently more qualified; its exact artifact and topology\nstill need evidence.\n\n## Follow the complete request path\n\nA native client enters at the transport boundary. An MCP or A2A client first\npasses through its compatibility adapter. Both paths converge on the same\ncentral action lifecycle before choosing local or remote execution.\n\n```mermaid\nflowchart LR\n    F[\"Foreign-protocol client\"] --> P[\"Compatibility profile\"]\n    N[\"Native AIP client\"] --> T[\"Native transport\"]\n    T --> G[\"Central gateway: authenticate and enrich identity\"]\n    P --> G\n    G --> R[\"Runtime: validate, authorize, approve, and persist\"]\n    R --> D{\"Connector placement\"}\n    D -->|\"Local\"| L[\"Trusted local handler\"]\n    D -->|\"Fleet\"| A[\"Tenant binding and durable route assignment\"]\n    A --> H[\"Signed native AIP request to connector host\"]\n    H --> V[\"Host verifies gateway, route, lease, revision, and capacity\"]\n    L --> C[\"Product connector\"]\n    V --> C\n    C --> X[\"Provider API or event surface\"]\n    X --> C\n    C --> O[\"AIP result, chunk, or event\"]\n    O --> R\n    R --> T\n```\n\nIn text, the flow is:\n\n1. A native binding decodes an AIP envelope, or a compatibility adapter maps a\n   foreign request into the native model.\n2. The central gateway authenticates the transport actor and resolves trusted\n   tenant and credential context.\n3. The runtime validates the capability and schema, evaluates policy and\n   approval, establishes transaction and idempotency state, and persists the\n   action lifecycle.\n4. A local capability selects its admitted local handler. A fleet capability\n   instead selects an enabled tenant binding and persists an action-scoped\n   route assignment before an external side effect.\n5. The remote dispatcher signs the envelope for the exact assigned host. The\n   host verifies the gateway, recipient, tenant, instance, replica, version,\n   manifest, capability, credential revision, lease, and local capacity.\n6. The product connector invokes the provider under the trusted context. Its\n   typed result or failure returns to the central runtime, which remains the\n   client-facing lifecycle owner.\n\nThis flow is an ownership map, not a guarantee that every deployment enables\nevery stage. Durable stores, authenticators, policies, admitted artifacts,\nbindings, hosts, and provider credentials must all be configured independently.\n\n## Read fleet identities from stable to ephemeral\n\nRemote routing uses several records so that a product name, tenant account,\nrunning process, and one action are not collapsed into a single “connector.”\n\n| Record | Stable meaning | Routing role |\n|---|---|---|\n| Connector type | One implementation family and owner | Allows or blocks admission of versions and instances |\n| Connector version | One immutable artifact, manifest, digest, attestation set, and implementation-support map | Defines the exact admitted code and contract |\n| Connector instance | One tenant-owned configured installation on a selected version | Names the logical provider account and secret-provider reference |\n| Connector replica | One live host process for an instance and version | Advertises a control-plane-selected endpoint, peer identity, topology, lease, health, and capacity |\n| Capability binding | One verified tenant and capability mapped to an enabled instance | Applies priority and policy, credential-revision, and quota references |\n| Route assignment | One immutable action-scoped execution target | Pins instance, replica, endpoint, peer, topology, version, digests, policy, credential revision, health, and fencing data |\n\nNew route selection considers enabled bindings and instances, admitted active\nversions, ready unexpired replicas, capacity, policy, circuit state, and\ntopology. Once persisted, the assignment is reused for that action's retries,\ncancellation, and reconciliation. A retry does not silently select a different\nprovider account or host.\n\n## Split ownership across the fleet boundary\n\n| Component | Owns | Must not be treated as owning |\n|---|---|---|\n| Central gateway and runtime | Client authentication, trusted identity enrichment, policy, approval, idempotency, transaction state, action lifecycle, and original callback | Provider secrets or host process health |\n| Registry and admission data | Connector types and versions, artifact evidence, tenant instances and bindings, replicas, leases, health, capacity, and durable routes | Provider invocation or client identity authentication |\n| Connector control plane | Signed host registration, heartbeat, drain, and offline transitions | Catalog migration, artifact admission, or product execution |\n| Connector host | One logical instance and immutable version, provider credentials, local durability, connector health, lease renewal, and signed native AIP ingress | Global tenant selection or caller-supplied identity |\n| Product connector | Provider mapping, product calls, provider errors, and supported recovery behavior | Central action governance or fleet routing policy |\n\nThe host serves health, readiness, metrics, its immutable manifest, and native\nmessage ingress. Readiness requires a valid lease, a non-draining state,\navailable durable storage, and connector readiness. For new actions, the host\nalso enforces local capacity and the route coordinates pinned by the central\nassignment.\n\n## Return results through the central owner\n\nA normal remote invocation returns a signed `ActionResult` directly to the\ncentral dispatcher. The dispatcher verifies that the returned action ID and\npeer match the assignment before the runtime settles the action.\n\nFor a streaming action, the remote dispatcher removes arbitrary client\ncallbacks and supplies only the configured central connector-callback endpoint\nwith signed route metadata. The shared central ingress validates the sender,\nreplica, instance, version, manifest, lease, and durable assignment before it\npublishes a chunk into runtime state. The central runtime retains the original\nclient callback.\n\nProvider-originated events use a separate fixed connector-event ingress. A\nhost can durably enqueue and sign those events, but event ingress does not make\nthe event an action result. Stream callbacks and provider events have different\ncorrelation and authorization rules.\n\n## Fleet routing is not delegation\n\nRemote connector execution sends an ordinary action to an implementation\nselected for a tenant capability. It does not create a parent-child action edge\nor transfer work to another agent principal under a `DelegationRequest`.\n\nUse delegation when one participant explicitly asks another participant to\nexecute a child action and the graph relationship matters. Use connector fleet\nrouting when the central runtime is selecting an implementation of the same\ngoverned action. The two paths may both use signed native AIP envelopes, but\ntheir identities, records, and lifecycle meanings remain distinct.\n\n## Choose the extension point by responsibility\n\n| Need | Correct extension point | Reason |\n|---|---|---|\n| Move native envelopes over a new network mechanism | Transport binding | Framing and delivery change; action meaning does not |\n| Serve MCP, A2A, or another general protocol | Compatibility profile plus its edge server | Foreign methods and objects require deterministic projection into the native model |\n| Invoke or receive events from one product | Product connector | Provider credentials, DTOs, side effects, and errors are product-specific |\n| Isolate connector code, secrets, rollout, or capacity | Remote connector host and fleet records | Process placement and routing need explicit trust and lifecycle controls |\n| Ask another AIP participant to execute a child action | Delegation route | The operation creates a first-class parent-child graph edge |\n\nDo not introduce a compatibility profile merely because one provider has\nunusual endpoints. Do not place a general protocol mapping inside one product\nconnector. Do not introduce a new transport to encode product-specific\nbusiness semantics.\n\n## Understand the trade-offs and limits\n\n- Native bindings preserve AIP concepts directly; compatibility profiles make\n  existing ecosystems accessible but require careful loss and error mapping.\n- Local connectors have fewer moving parts; remote hosts isolate secrets and\n  failures but add routing, lease, signing, and recovery dependencies.\n- Manifest advertisement supports discovery; registry admission and live\n  readiness provide stronger, still bounded evidence.\n- A capability binding expresses tenant policy; an action-scoped route freezes\n  the exact execution target before side effects.\n- A signed remote response authenticates a configured peer under the reviewed\n  verification path; it does not by itself prove provider-side behavior.\n\nThis page does not claim that all transports support all message patterns, that\nevery advertised profile has a live endpoint, or that a connector manifest\nproves conformance. It also does not claim production readiness for any of the\nsix maintained product connectors. Those conclusions require exact-artifact,\ntopology, provider, and retained-evidence review.\n\n## Related concepts\n\n- Read [Capabilities and contracts](capabilities.md) for the semantic unit a\n  connector implements.\n- Read [Identity and trust](identity-and-trust.md) for the actor, tenant,\n  credential, and route authority boundaries.\n- Read [Delegation](delegation.md) before routing work to another AIP\n  participant.\n- Use [Build a connector](../guides/build-a-connector.md) for the implementation\n  procedure.\n- See [Connector registry and routing](../architecture/connector-registry-and-routing.md)\n  for the detailed fleet data model and selection algorithm.\n",
    "text": "Profiles, transports, and connectors\n\nUse this page to choose the correct integration boundary without creating a\nsecond action model or bypassing AIP governance. It is for application,\ngateway, and connector developers who need to distinguish protocol semantics,\nwire delivery, compatibility mapping, product behavior, and process placement.\n\nAIP has one native semantic model. A transport moves that model, a\ncompatibility profile projects another protocol onto it, and a connector maps\nan AIP capability to a product. A connector can run inside a trusted process or\nbehind a separately deployed connector host. Placement changes the trust and\nfailure boundary, but it does not change the meaning of the action.\n\nThis page describes the reviewed Rust implementation of AIP 1.0 at source\nrevision 97be86e9efedf07ecf1783b03800f683f107fb04. It explains architecture,\nnot production qualification. The maintained public connector set in this\ndocumentation is Cal.diy, Hermes Agent, Chatwoot, Dify, CrewAI, and Twenty.\n\nKeep four integration layers separate\n\nThe layers compose, but none substitutes for another.\n\n| Layer | Question it answers | What it owns | What it does not own |\n\n| AIP semantics | What work is requested, governed, and observed? | Envelopes, actions, capabilities, identity claims, lifecycle, approvals, transactions, errors, and evidence | A provider API or network connection |\n| Transport binding | How does a native AIP envelope move between peers? | Framing, encoding, connection behavior, delivery metadata, and transport errors | Capability authorization or provider behavior |\n| Compatibility profile | How does another protocol project onto AIP? | Foreign data-transfer objects (DTOs), deterministic mappings, method and error projection, and compatibility metadata | A parallel action store or product credentials |\n| Product connector | How does a product perform the requested capability? | Provider DTOs, authentication at the provider edge, invocation, error normalization, and supported recovery behavior | Global identity, policy, approval, or action lifecycle |\n\nProcess placement is a separate decision. The same product connector contract\ncan be registered as a trusted local handler or hosted behind the connector\nfleet boundary. Treating placement as a fifth protocol layer would confuse a\ndeployment choice with wire semantics.\n\nA profile identifier is a declaration\n\nProfileId is a general namespace used across discovery and bindings. A\nparticipant manifest advertises supported profile identifiers. A manifest\nrequest and its filter can select them, and an individual capability binding\ncan attach profile-specific metadata.\n\nThe namespace is broader than “compatibility protocol.” The reviewed source\nuses profile identifiers for all of these purposes:\n• native transport bindings, such as aip.native.nats.v1;\n• streaming bindings, such as aip.sse.stream.v1 and\n  aip.websocket.stream.v1;\n• compatibility mappings, such as aip.mcp.compat.v1 and\n  aip.a2a.compat.v1;\n• the generic signed-webhook contract aip.http.webhook.v1;\n• connector-specific capability bindings.\n\nAn advertised identifier says that the publisher declares compatibility with\nthat namespace. It does not prove that an endpoint is reachable, a route has\nbeen admitted, the peer is authenticated, the caller is authorized, or a live\nreplica is ready. Those checks belong to transport, identity, registry, and\nruntime boundaries.\n\nNative transports preserve the envelope\n\nThe shared transport abstraction carries a native Envelope with normalized\nmetadata. Request/reply and streaming behavior are separate traits, so a\ntransport implementation does not imply support for every interaction pattern.\n\n| Binding | Native behavior in the reviewed source | Appropriate use |\n\n| HTTP | Encodes an envelope as JSON with application/aip+json; recommends message, action, and manifest paths; maps protocol error categories to HTTP status classes | Common service ingress and request/reply |\n| NATS | Publishes or requests native envelopes on structured AIP subjects, with optional queue groups and correlation streams | Brokered service routing and workers |\n| SSE | Encodes native envelopes as one-way events, preserves event identifiers for reconnection, and marks results, errors, and final chunks as terminal | Following events or streamed output over HTTP |\n| WebSocket | Encodes envelopes as text frames and provides session queues, correlation subscriptions, ping/pong, and close behavior | Authenticated bidirectional multiplexing |\n\nChanging the binding does not change an action ID, capability contract,\nidentity rules, approval state, transaction state, or result meaning. Transport\nauthentication also does not grant capability authority. The gateway must\nstill establish a trusted actor and apply policy before execution.\n\nThe transport crates provide reusable framing and state. A concrete server\nmust still expose routes, authenticate connections, apply limits, and connect\nframes to the gateway. The product-neutral daemon supplies those server\nboundaries for its configured HTTP, SSE, WebSocket, and NATS surfaces.\n\nCompatibility profiles translate at the edge\n\nA compatibility profile lets a client use an established protocol while AIP\nremains the internal semantic and lifecycle authority.\n\nThe MCP profile owns MCP DTOs and deterministic mappings between tool,\nresource, task, progress, error, and AIP concepts. It deliberately contains no\nHTTP server, subprocess, or runtime state. Those responsibilities stay in the\nMCP server, client, and transport components.\n\nThe A2A profile similarly maps Agent Cards, messages, tasks, status updates,\nstreaming, cancellation, and push-notification concepts. The signed-webhook\nprofile is narrower: it defines normalized webhook headers and verifies an\nHMAC-SHA256 signature with a timestamp-skew boundary. A product connector still\nhas to interpret the verified provider event.\n\nA profile adapter should therefore perform three bounded steps:\n1. validate the foreign request under that protocol's rules;\n2. create or address the corresponding native AIP operation;\n3. project the native result, status, stream, resource, or error back to the\n   foreign protocol.\n\nThe native action remains authoritative throughout the second step. A profile\nmust not create a separate approval engine, transaction store, or connector\ncredential path merely because the foreign protocol names those concepts\ndifferently.\n\nA connector implements product behavior\n\nThe base connector contract identifies a connector, discovers its manifest,\nmaps failures, and reports health. Additional traits make supported behavior\nexplicit: capability discovery, outbound invocation, channel ingress and\negress, external-event ingestion, escalation, and typed transaction or recovery\noperations.\n\nThe production typed boundary, FrozenConnector, receives a complete trusted\nexecution context. It can implement normal invocation, planning, commit,\ncompensation, cancellation, reconciliation, emission, and ingestion. Every\noptional operation fails as unsupported unless the connector overrides it.\nThat default prevents an advertised capability from silently acquiring safety\nproperties that its provider does not implement.\n\nA product connector owns only its product edge. Typical responsibilities are:\n• converting a capability input into provider requests;\n• loading credential material from connector-owned process storage;\n• pinning the correct provider account from trusted execution context;\n• normalizing provider responses and failures into AIP results;\n• retaining provider operation references needed for reconciliation;\n• verifying product webhooks before mapping them to AIP envelopes;\n• declaring implementation support that matches the admitted artifact.\n\nThe connector does not trust caller-supplied tenant or credential values. It\nalso does not decide the global approval policy, rewrite the AIP lifecycle, or\nprove its own qualification merely by publishing a manifest.\n\nChoose local or remote placement deliberately\n\nThe reviewed implementation supports two materially different placements.\n\n| Placement | Execution path | Trust and operations boundary |\n\n| Trusted local module | The gateway discovers the connector manifest, admits callable capabilities with local handlers, and invokes the connector with runtime-established context | Connector code, credentials, failures, and resource use share the gateway process boundary |\n| Remote connector fleet | The central runtime resolves a tenant-scoped route, sends a signed native AIP action to a registered host, and verifies the signed response | Provider credentials and connector code stay in a separately leased, observable, and drainable host process |\n\nThe typed local path wraps each admitted non-resource capability in a handler.\nThe handler rejects calls without trusted execution context and selects the\nconnector operation from the action transaction mode. Local placement reduces\nnetwork and control-plane machinery, but it also increases the blast radius of\nconnector faults and may place provider secrets in the central process.\n\nThe remote path adds registry, route, identity, lease, capacity, and callback\nboundaries. That machinery supports independent rollout and isolation, but it\nalso requires durable control-plane state and another authenticated hop. Remote\nplacement is not inherently more qualified; its exact artifact and topology\nstill need evidence.\n\nFollow the complete request path\n\nA native client enters at the transport boundary. An MCP or A2A client first\npasses through its compatibility adapter. Both paths converge on the same\ncentral action lifecycle before choosing local or remote execution.\n\nflowchart LR\n    F[\"Foreign-protocol client\"] --> P[\"Compatibility profile\"]\n    N[\"Native AIP client\"] --> T[\"Native transport\"]\n    T --> G[\"Central gateway: authenticate and enrich identity\"]\n    P --> G\n    G --> R[\"Runtime: validate, authorize, approve, and persist\"]\n    R --> D{\"Connector placement\"}\n    D -->|\"Local\"| L[\"Trusted local handler\"]\n    D -->|\"Fleet\"| A[\"Tenant binding and durable route assignment\"]\n    A --> H[\"Signed native AIP request to connector host\"]\n    H --> V[\"Host verifies gateway, route, lease, revision, and capacity\"]\n    L --> C[\"Product connector\"]\n    V --> C\n    C --> X[\"Provider API or event surface\"]\n    X --> C\n    C --> O[\"AIP result, chunk, or event\"]\n    O --> R\n    R --> T\n\nIn text, the flow is:\n1. A native binding decodes an AIP envelope, or a compatibility adapter maps a\n   foreign request into the native model.\n2. The central gateway authenticates the transport actor and resolves trusted\n   tenant and credential context.\n3. The runtime validates the capability and schema, evaluates policy and\n   approval, establishes transaction and idempotency state, and persists the\n   action lifecycle.\n4. A local capability selects its admitted local handler. A fleet capability\n   instead selects an enabled tenant binding and persists an action-scoped\n   route assignment before an external side effect.\n5. The remote dispatcher signs the envelope for the exact assigned host. The\n   host verifies the gateway, recipient, tenant, instance, replica, version,\n   manifest, capability, credential revision, lease, and local capacity.\n6. The product connector invokes the provider under the trusted context. Its\n   typed result or failure returns to the central runtime, which remains the\n   client-facing lifecycle owner.\n\nThis flow is an ownership map, not a guarantee that every deployment enables\nevery stage. Durable stores, authenticators, policies, admitted artifacts,\nbindings, hosts, and provider credentials must all be configured independently.\n\nRead fleet identities from stable to ephemeral\n\nRemote routing uses several records so that a product name, tenant account,\nrunning process, and one action are not collapsed into a single “connector.”\n\n| Record | Stable meaning | Routing role |\n\n| Connector type | One implementation family and owner | Allows or blocks admission of versions and instances |\n| Connector version | One immutable artifact, manifest, digest, attestation set, and implementation-support map | Defines the exact admitted code and contract |\n| Connector instance | One tenant-owned configured installation on a selected version | Names the logical provider account and secret-provider reference |\n| Connector replica | One live host process for an instance and version | Advertises a control-plane-selected endpoint, peer identity, topology, lease, health, and capacity |\n| Capability binding | One verified tenant and capability mapped to an enabled instance | Applies priority and policy, credential-revision, and quota references |\n| Route assignment | One immutable action-scoped execution target | Pins instance, replica, endpoint, peer, topology, version, digests, policy, credential revision, health, and fencing data |\n\nNew route selection considers enabled bindings and instances, admitted active\nversions, ready unexpired replicas, capacity, policy, circuit state, and\ntopology. Once persisted, the assignment is reused for that action's retries,\ncancellation, and reconciliation. A retry does not silently select a different\nprovider account or host.\n\nSplit ownership across the fleet boundary\n\n| Component | Owns | Must not be treated as owning |\n\n| Central gateway and runtime | Client authentication, trusted identity enrichment, policy, approval, idempotency, transaction state, action lifecycle, and original callback | Provider secrets or host process health |\n| Registry and admission data | Connector types and versions, artifact evidence, tenant instances and bindings, replicas, leases, health, capacity, and durable routes | Provider invocation or client identity authentication |\n| Connector control plane | Signed host registration, heartbeat, drain, and offline transitions | Catalog migration, artifact admission, or product execution |\n| Connector host | One logical instance and immutable version, provider credentials, local durability, connector health, lease renewal, and signed native AIP ingress | Global tenant selection or caller-supplied identity |\n| Product connector | Provider mapping, product calls, provider errors, and supported recovery behavior | Central action governance or fleet routing policy |\n\nThe host serves health, readiness, metrics, its immutable manifest, and native\nmessage ingress. Readiness requires a valid lease, a non-draining state,\navailable durable storage, and connector readiness. For new actions, the host\nalso enforces local capacity and the route coordinates pinned by the central\nassignment.\n\nReturn results through the central owner\n\nA normal remote invocation returns a signed ActionResult directly to the\ncentral dispatcher. The dispatcher verifies that the returned action ID and\npeer match the assignment before the runtime settles the action.\n\nFor a streaming action, the remote dispatcher removes arbitrary client\ncallbacks and supplies only the configured central connector-callback endpoint\nwith signed route metadata. The shared central ingress validates the sender,\nreplica, instance, version, manifest, lease, and durable assignment before it\npublishes a chunk into runtime state. The central runtime retains the original\nclient callback.\n\nProvider-originated events use a separate fixed connector-event ingress. A\nhost can durably enqueue and sign those events, but event ingress does not make\nthe event an action result. Stream callbacks and provider events have different\ncorrelation and authorization rules.\n\nFleet routing is not delegation\n\nRemote connector execution sends an ordinary action to an implementation\nselected for a tenant capability. It does not create a parent-child action edge\nor transfer work to another agent principal under a DelegationRequest.\n\nUse delegation when one participant explicitly asks another participant to\nexecute a child action and the graph relationship matters. Use connector fleet\nrouting when the central runtime is selecting an implementation of the same\ngoverned action. The two paths may both use signed native AIP envelopes, but\ntheir identities, records, and lifecycle meanings remain distinct.\n\nChoose the extension point by responsibility\n\n| Need | Correct extension point | Reason |\n\n| Move native envelopes over a new network mechanism | Transport binding | Framing and delivery change; action meaning does not |\n| Serve MCP, A2A, or another general protocol | Compatibility profile plus its edge server | Foreign methods and objects require deterministic projection into the native model |\n| Invoke or receive events from one product | Product connector | Provider credentials, DTOs, side effects, and errors are product-specific |\n| Isolate connector code, secrets, rollout, or capacity | Remote connector host and fleet records | Process placement and routing need explicit trust and lifecycle controls |\n| Ask another AIP participant to execute a child action | Delegation route | The operation creates a first-class parent-child graph edge |\n\nDo not introduce a compatibility profile merely because one provider has\nunusual endpoints. Do not place a general protocol mapping inside one product\nconnector. Do not introduce a new transport to encode product-specific\nbusiness semantics.\n\nUnderstand the trade-offs and limits\n• Native bindings preserve AIP concepts directly; compatibility profiles make\n  existing ecosystems accessible but require careful loss and error mapping.\n• Local connectors have fewer moving parts; remote hosts isolate secrets and\n  failures but add routing, lease, signing, and recovery dependencies.\n• Manifest advertisement supports discovery; registry admission and live\n  readiness provide stronger, still bounded evidence.\n• A capability binding expresses tenant policy; an action-scoped route freezes\n  the exact execution target before side effects.\n• A signed remote response authenticates a configured peer under the reviewed\n  verification path; it does not by itself prove provider-side behavior.\n\nThis page does not claim that all transports support all message patterns, that\nevery advertised profile has a live endpoint, or that a connector manifest\nproves conformance. It also does not claim production readiness for any of the\nsix maintained product connectors. Those conclusions require exact-artifact,\ntopology, provider, and retained-evidence review.\n\nRelated concepts\n• Read Capabilities and contracts (capabilities.md) for the semantic unit a\n  connector implements.\n• Read Identity and trust (identity-and-trust.md) for the actor, tenant,\n  credential, and route authority boundaries.\n• Read Delegation (delegation.md) before routing work to another AIP\n  participant.\n• Use Build a connector (../guides/build-a-connector.md) for the implementation\n  procedure.\n• See Connector registry and routing (../architecture/connector-registry-and-routing.md)\n  for the detailed fleet data model and selection algorithm.\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "5fcdda91fef01da11dc4831787a89263296a1714387152207578506408567a97"
  }
}