{
  "schemaVersion": "1.0",
  "title": "Use native AIP",
  "description": "Use this guide when a client needs the complete AIP action lifecycle without projecting it through MCP, A2A, or another compatibility protocol. You will discover a capability, invoke it with a stable action identity, follow durable state, a",
  "canonical": "https://getaip.org/docs/guides/use-native-aip",
  "route": "/docs/guides/use-native-aip",
  "source": "docs/guides/use-native-aip.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Build with AIP",
  "documentType": "Guide",
  "language": "en",
  "revision": {
    "lastReviewedRevision": "d7cce13d1d555644d04a4d73c66c95b113737635",
    "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb",
    "basis": "frontmatter"
  },
  "downloads": {
    "md": "/docs/download/guides/use-native-aip.md",
    "txt": "/docs/download/guides/use-native-aip.txt",
    "json": "/docs/download/guides/use-native-aip.json",
    "pdf": "/docs/download/guides/use-native-aip.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Use native AIP\ndescription: Discover, invoke, follow, retry, and cancel a native AIP action without choosing its connector route\nkind: how-to\naudience: developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"d7cce13d1d555644d04a4d73c66c95b113737635\"\n---\n\n# Use native AIP\n\nUse this guide when a client needs the complete AIP action lifecycle without\nprojecting it through MCP, A2A, or another compatibility protocol. You will\ndiscover a capability, invoke it with a stable action identity, follow durable\nstate, and request cancellation. The same client procedure works for a local\nhandler and for a remote connector selected by the fleet.\n\nThis guide applies to AIP 1.0 and the Rust implementation at source revision\n`d7cce13d1d555644d04a4d73c66c95b113737635`. The commands were checked against\nthat source; this documentation pass did not start a daemon or execute a\nprovider operation.\n\n## Prerequisites\n\nYou need:\n\n- a `getaip-server` and `getaip` build from the reviewed revision;\n- the base URL of a native AIP endpoint;\n- a native HTTP bearer credential accepted by that endpoint;\n- permission to invoke and read the selected action;\n- `curl` and two terminals for the optional loopback setup.\n\nRun the loopback commands from the reviewed repository root.\n\nFor a remote connector capability, the deployment must also have an enabled\nconnector registry, an active admitted version, an enabled tenant binding, and\nan eligible connector-host replica. The authenticated principal needs a\ndeployment-owned trusted identity binding that resolves the execution tenant.\n\nThe daemon's `--native-tenant-id` option has a narrower role: it binds the\nstatic bearer credential to tenant-scoped HTTP capability discovery. It does\nnot, by itself, establish the trusted tenant used for remote execution.\n\n## 1. Prepare an optional loopback endpoint\n\nSkip this step if you already have a native endpoint. For a local development\nendpoint, create an owner-only bearer-token file:\n\n```sh\numask 077\nprintf '%s\\n' 'local-development-token' > .aip-native-token\n```\n\nStart the product-neutral daemon in the first terminal:\n\n```sh\ncargo run --locked -p getaip-server -- \\\n  --bind 127.0.0.1:18080 \\\n  --service-id agent:getaip:server:native-guide \\\n  --native-bearer-token-file .aip-native-token \\\n  --native-principal agent:getaip:cli \\\n  --native-principal-scope action:read \\\n  --storage-dir .getaip-server-native-guide\n```\n\nLeave the process running. This command is restricted to loopback and uses a\ndedicated local state directory. It does not configure a connector registry,\ntenant catalog, remote host, or production identity provider.\n\nCheck readiness from the second terminal:\n\n```sh\ncurl --fail --silent --show-error http://127.0.0.1:18080/ready\n```\n\nExpected result: HTTP `200` with `\"status\": \"ready\"`. Readiness proves the\nconfigured daemon boundary is ready. It does not prove that an unconfigured\nconnector or provider is reachable.\n\nSet reusable client variables:\n\n```sh\nexport AIP_URL=http://127.0.0.1:18080\nexport AIP_TOKEN_FILE=.aip-native-token\n```\n\nFor a non-loopback deployment, use HTTPS, owner-only credential files, and the\ndeployment's expected peer DID and trust material. `getaip` supports a native\nsigning-seed file, a pinned peer-DID file, a private-PKI CA file, and a bounded\nresponse size. Raw `curl` does not provide the same signed-response checks.\n\n## 2. Fetch the participant manifest\n\nFetch the endpoint's native manifest before invoking a capability:\n\n```sh\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token-file \"$AIP_TOKEN_FILE\" \\\n  manifest fetch \"$AIP_URL\"\n```\n\nFor the loopback daemon, the manifest identifies\n`agent:getaip:server:native-guide` and includes the built-in\n`cap:aip:server:health` capability. It also advertises the profiles enabled by that\ndaemon.\n\nThe manifest describes one participant's complete declared surface. It is not\nthe same as the connector fleet's tenant-filtered catalog. A manifest may\ninclude local capabilities that are unrelated to connector bindings, while a\ntenant catalog can contain capabilities admitted from many connector versions.\n\n## 3. Invoke one local native action\n\nCall the built-in health capability with a stable action ID:\n\n```sh\nexport AIP_ACTION_ID=act_native_guide_health_001\n\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token-file \"$AIP_TOKEN_FILE\" \\\n  action call \"$AIP_URL\" \\\n  cap:aip:server:health \\\n  --action-id \"$AIP_ACTION_ID\" \\\n  --mode sync \\\n  --input '{}'\n```\n\nExpected result: an `aip.core.v1.action_result` envelope whose action ID is\n`act_native_guide_health_001` and whose status is `completed`. Store the action\nID even when the first response is terminal. Durable state, not the lifetime\nof the HTTP connection, owns the action lifecycle.\n\nThe bearer edge authenticates this request as the daemon-configured\n`agent:getaip:cli` principal. An identity or `from` value inside the request is a\nclaim and cannot override that authenticated actor.\n\n## 4. Discover a tenant-visible fleet capability\n\nUse this step against an endpoint whose connector catalog is enabled. Point\n`AIP_URL` and `AIP_TOKEN_FILE` at that deployment, then request the first\nbounded page:\n\n```sh\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token-file \"$AIP_TOKEN_FILE\" \\\n  capability list \"$AIP_URL\" \\\n  --limit 50\n```\n\nThe response contains:\n\n- `catalog_revision`, which identifies the registry view used for the page;\n- `capabilities`, a list of capability definitions and their contract and\n  schema digests;\n- `next_cursor`, an opaque cursor when another page exists;\n- `total`, the total matches at that revision.\n\nThe bearer credential must be mapped to a tenant for this HTTP route. The\ncatalog returns only capabilities with an enabled binding for that tenant, an\nenabled connector instance, an active version, and an enabled connector type.\nAn optional `--profile` filter selects versions whose manifest advertises that\nprofile.\n\nCatalog visibility is admission evidence, not liveness evidence. The query\ndoes not require a ready replica. Route selection can still fail later if no\neligible host has a valid lease and available capacity.\n\nTo continue pagination, pass the exact `next_cursor` returned by the preceding\npage:\n\n```sh\nexport NEXT_CURSOR='paste-the-exact-next_cursor-value'\n\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token-file \"$AIP_TOKEN_FILE\" \\\n  capability list \"$AIP_URL\" \\\n  --cursor \"$NEXT_CURSOR\" \\\n  --limit 50\n```\n\nDo not combine a cursor with pages from another catalog revision. If the\nserver reports `connector_catalog.stale_cursor`, discard the old cursor and\nrestart from the first page.\n\n## 5. Check the selected contract\n\nBefore invoking a catalog capability, inspect its complete definition. At a\nminimum, record and evaluate:\n\n- the exact capability ID, contract digest, and schema digest;\n- the input and output schemas;\n- declared execution modes and streaming behavior;\n- side effects, risk, and human-approval requirements;\n- idempotency key requirements and scope;\n- transaction, reconciliation, cancellation, and compensation support;\n- credential and data boundaries;\n- profile bindings required by the client.\n\nDo not infer these properties from a display name. If the contract changed\nsince the caller last evaluated it, repeat the caller's policy and input\ndecision against the new revision before submitting work.\n\n## 6. Invoke without choosing a connector host\n\nPrepare the selected input as a JSON object and keep the identifiers outside\nthe file:\n\n```sh\nexport AIP_CAPABILITY_ID='cap:replace:with:catalog-id'\nexport AIP_ACTION_ID='act_replace_with_stable_id_001'\n\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token-file \"$AIP_TOKEN_FILE\" \\\n  action call \"$AIP_URL\" \\\n  \"$AIP_CAPABILITY_ID\" \\\n  --action-id \"$AIP_ACTION_ID\" \\\n  --input @request.json\n```\n\nAdd `--mode`, `--idempotency-key`, approval, or transaction options only as\nrequired by the selected contract. For a replay-sensitive mutation, retain the\noriginal action ID, idempotency key, transaction ID, and plan ID together.\n\nDo not send an instance ID, replica ID, host URL, connector version, or\ncredential reference. The central runtime uses the verified execution tenant\nand capability ID to resolve an enabled binding. It persists an action-scoped\nroute before dispatch and sends a signed native AIP envelope to the assigned\nhost. The host then rechecks the pinned route and trusted gateway identity.\n\nThe client sees the ordinary AIP action lifecycle in both placements. A local\ncapability runs through its admitted in-process handler. A fleet capability\nruns through the remote handler, registry assignment, and connector host. A\nclient retry with the same action identity does not authorize choosing another\nprovider account or replica.\n\n## 7. Read or follow the durable action\n\nRead the current lifecycle view independently of the submission response:\n\n```sh\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token-file \"$AIP_TOKEN_FILE\" \\\n  action status \"$AIP_URL\" \\\n  \"$AIP_ACTION_ID\" \\\n  --include-result \\\n  --include-receipts\n```\n\nFor long-running or streaming work, follow action-scoped events and chunks:\n\n```sh\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token-file \"$AIP_TOKEN_FILE\" \\\n  action events \"$AIP_URL\" \\\n  \"$AIP_ACTION_ID\" \\\n  --include-chunks \\\n  --follow\n```\n\nPersist the last acknowledged cursor before reconnecting. A resumed consumer\nmust tolerate replay. A cursor orders the retained event view; it is not an\nexactly-once delivery token.\n\nIf the submission connection failed before a response, query the stable action\nID first. Retry only under the capability's idempotency and uncertainty rules,\nusing every original identity. Generating a new action ID creates a new logical\noperation and can permit another provider effect.\n\n## 8. Request cancellation\n\nRequest cancellation of the same durable action:\n\n```sh\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token-file \"$AIP_TOKEN_FILE\" \\\n  action cancel \"$AIP_URL\" \\\n  \"$AIP_ACTION_ID\" \\\n  --reason 'The requester withdrew the operation'\n```\n\nFor a fleet action, cancellation uses the persisted route assignment rather\nthan resolving a new host. The runtime records cancellation intent, but a\nprovider mutation may already have completed or may not support remote\ncancellation. Query the action and any transaction or reconciliation state\nbefore deciding that another mutation is safe.\n\n## 9. Send a raw envelope when necessary\n\nUse the generic native message endpoint when implementing a client or testing\na message family without an ergonomic CLI command. Keep this example on the\nloopback endpoint from step 1:\n\n```sh\nexport AIP_URL=http://127.0.0.1:18080\nexport AIP_TOKEN_FILE=.aip-native-token\n```\n\nSave this example as `action-envelope.json` and replace `sent_at` with the\ncurrent RFC 3339 time:\n\n```json\n{\n  \"aip_version\": \"1.0\",\n  \"message_type\": \"aip.core.v1.action\",\n  \"message_id\": \"msg_native_guide_raw_0001\",\n  \"sent_at\": \"2026-07-26T20:00:00Z\",\n  \"from\": {\n    \"id\": \"agent:getaip:cli\",\n    \"kind\": \"agent\"\n  },\n  \"body\": {\n    \"action\": {\n      \"id\": \"act_native_guide_raw_0001\",\n      \"capability_id\": \"cap:aip:server:health\",\n      \"input\": {},\n      \"mode\": \"sync\"\n    }\n  }\n}\n```\n\nLoad the development token without placing it literally in the command:\n\n```sh\nAIP_TOKEN=$(tr -d '\\r\\n' < \"$AIP_TOKEN_FILE\")\n\ncurl --fail-with-body \\\n  -H \"Authorization: Bearer $AIP_TOKEN\" \\\n  -H 'Content-Type: application/aip+json' \\\n  --data @action-envelope.json \\\n  \"$AIP_URL/aip/v1/messages\"\n\nunset AIP_TOKEN\n```\n\nThe endpoint validates the envelope schema and dispatches the typed body. With\nbearer authentication, the configured edge principal is authoritative; the\npayload's `from` field does not establish identity.\n\nFor signed peer traffic,\nuse a client that signs the envelope, pins the expected peer DID, verifies the\nresponse signature and correlation, rejects redirects, and limits response\nsize. `getaip` implements those checks when its native signing options are\nconfigured.\n\n## Verify the outcome\n\nFor the loopback path, require readiness and the stored local result:\n\n```sh\ncurl --fail --silent --show-error \"$AIP_URL/ready\" >/dev/null\n\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token-file \"$AIP_TOKEN_FILE\" \\\n  action status \"$AIP_URL\" \\\n  act_native_guide_health_001 \\\n  --include-result >/dev/null\n```\n\nBoth commands must exit with status `0`. For a fleet capability, also confirm\nthat the terminal result belongs to the original action ID and that any\nrequired receipt, transaction, or reconciliation evidence is present. A\nsuccessful call demonstrates only the configured path and provider response;\nit is not connector qualification or a production-readiness claim.\n\n## Stop and clean up the loopback state\n\nStop the local daemon with `Control-C`. Keep `.getaip-server-native-guide` if you need to\nrestart the daemon and inspect the same action. When the local history and\ndevelopment credential are no longer needed, inspect and remove only those two\npaths:\n\n```sh\ndu -sh .getaip-server-native-guide\nls -l .aip-native-token\nrm -rf -- .getaip-server-native-guide\nrm -- .aip-native-token\n```\n\nDo not apply this cleanup to a shared endpoint, connector registry, provider,\nor retained qualification evidence.\n\n## Resolve common failures\n\n| Symptom | Meaning | Safe next action |\n|---|---|---|\n| Native route returns `401` | Bearer credential is missing or invalid | Confirm the intended token file and endpoint; do not print the token |\n| Catalog returns `connector_catalog.disabled` | This daemon has no connector catalog | Configure the registry data plane or use the endpoint's manifest for local capabilities |\n| Catalog returns `connector_catalog.tenant_required` | The bearer identity has no discovery tenant | Bind the intended static credential with `--native-tenant-id`; do not copy a tenant from request data |\n| Catalog returns `connector_catalog.stale_cursor` | The registry changed during pagination | Restart from the first page and evaluate the new revision |\n| Capability is absent | No visible enabled binding and active version matched the tenant and filters | Check the tenant binding, instance, version, type, filters, and catalog revision |\n| Remote execution reports that a verified tenant is required | Discovery identity was configured, but runtime identity enrichment did not establish execution tenant | Correct the trusted identity binding for the authenticated principal; do not rely on `--native-tenant-id` |\n| Invocation has no eligible replica | Admission was visible, but no ready route has valid lease, capacity, and policy | Preserve the action identity and ask the operator to restore or drain the fleet deliberately |\n| Client disconnected after submission | The durable action outcome is unknown to the client | Query the original action ID before any retry |\n| Cancellation returns but the provider may have changed state | Cancellation is intent, not proof of rollback | Inspect the terminal action, provider operation, transaction, and reconciliation evidence |\n\n## Related documentation\n\n- Complete [the connector fleet quickstart](../getting-started/connector-fleet-quickstart.md)\n  to observe one deterministic remote path.\n- Read [Capabilities and contracts](../concepts/capabilities.md) before choosing\n  modes, retries, or transaction options.\n- Read [Actions and sessions](../concepts/actions-and-sessions.md) for lifecycle,\n  idempotency, events, and cancellation semantics.\n- Use the [Native HTTP API](../reference/http-api.md) for exhaustive route and\n  query syntax.\n- Use [Errors and retry decisions](../reference/errors.md) before automating\n  recovery.\n",
    "text": "Use native AIP\n\nUse this guide when a client needs the complete AIP action lifecycle without\nprojecting it through MCP, A2A, or another compatibility protocol. You will\ndiscover a capability, invoke it with a stable action identity, follow durable\nstate, and request cancellation. The same client procedure works for a local\nhandler and for a remote connector selected by the fleet.\n\nThis guide applies to AIP 1.0 and the Rust implementation at source revision\nd7cce13d1d555644d04a4d73c66c95b113737635. The commands were checked against\nthat source; this documentation pass did not start a daemon or execute a\nprovider operation.\n\nPrerequisites\n\nYou need:\n• a getaip-server and getaip build from the reviewed revision;\n• the base URL of a native AIP endpoint;\n• a native HTTP bearer credential accepted by that endpoint;\n• permission to invoke and read the selected action;\n• curl and two terminals for the optional loopback setup.\n\nRun the loopback commands from the reviewed repository root.\n\nFor a remote connector capability, the deployment must also have an enabled\nconnector registry, an active admitted version, an enabled tenant binding, and\nan eligible connector-host replica. The authenticated principal needs a\ndeployment-owned trusted identity binding that resolves the execution tenant.\n\nThe daemon's --native-tenant-id option has a narrower role: it binds the\nstatic bearer credential to tenant-scoped HTTP capability discovery. It does\nnot, by itself, establish the trusted tenant used for remote execution.\n1. Prepare an optional loopback endpoint\n\nSkip this step if you already have a native endpoint. For a local development\nendpoint, create an owner-only bearer-token file:\n\numask 077\nprintf '%s\\n' 'local-development-token' > .aip-native-token\n\nStart the product-neutral daemon in the first terminal:\n\ncargo run --locked -p getaip-server -- \\\n  --bind 127.0.0.1:18080 \\\n  --service-id agent:getaip:server:native-guide \\\n  --native-bearer-token-file .aip-native-token \\\n  --native-principal agent:getaip:cli \\\n  --native-principal-scope action:read \\\n  --storage-dir .getaip-server-native-guide\n\nLeave the process running. This command is restricted to loopback and uses a\ndedicated local state directory. It does not configure a connector registry,\ntenant catalog, remote host, or production identity provider.\n\nCheck readiness from the second terminal:\n\ncurl --fail --silent --show-error http://127.0.0.1:18080/ready\n\nExpected result: HTTP 200 with \"status\": \"ready\". Readiness proves the\nconfigured daemon boundary is ready. It does not prove that an unconfigured\nconnector or provider is reachable.\n\nSet reusable client variables:\n\nexport AIPURL=http://127.0.0.1:18080\nexport AIPTOKENFILE=.aip-native-token\n\nFor a non-loopback deployment, use HTTPS, owner-only credential files, and the\ndeployment's expected peer DID and trust material. getaip supports a native\nsigning-seed file, a pinned peer-DID file, a private-PKI CA file, and a bounded\nresponse size. Raw curl does not provide the same signed-response checks.\n2. Fetch the participant manifest\n\nFetch the endpoint's native manifest before invoking a capability:\n\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token-file \"$AIPTOKENFILE\" \\\n  manifest fetch \"$AIPURL\"\n\nFor the loopback daemon, the manifest identifies\nagent:getaip:server:native-guide and includes the built-in\ncap:aip:server:health capability. It also advertises the profiles enabled by that\ndaemon.\n\nThe manifest describes one participant's complete declared surface. It is not\nthe same as the connector fleet's tenant-filtered catalog. A manifest may\ninclude local capabilities that are unrelated to connector bindings, while a\ntenant catalog can contain capabilities admitted from many connector versions.\n3. Invoke one local native action\n\nCall the built-in health capability with a stable action ID:\n\nexport AIPACTIONID=actnativeguidehealth001\n\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token-file \"$AIPTOKENFILE\" \\\n  action call \"$AIPURL\" \\\n  cap:aip:server:health \\\n  --action-id \"$AIPACTIONID\" \\\n  --mode sync \\\n  --input '{}'\n\nExpected result: an aip.core.v1.actionresult envelope whose action ID is\nactnativeguidehealth001 and whose status is completed. Store the action\nID even when the first response is terminal. Durable state, not the lifetime\nof the HTTP connection, owns the action lifecycle.\n\nThe bearer edge authenticates this request as the daemon-configured\nagent:getaip:cli principal. An identity or from value inside the request is a\nclaim and cannot override that authenticated actor.\n4. Discover a tenant-visible fleet capability\n\nUse this step against an endpoint whose connector catalog is enabled. Point\nAIPURL and AIPTOKENFILE at that deployment, then request the first\nbounded page:\n\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token-file \"$AIPTOKENFILE\" \\\n  capability list \"$AIPURL\" \\\n  --limit 50\n\nThe response contains:\n• catalogrevision, which identifies the registry view used for the page;\n• capabilities, a list of capability definitions and their contract and\n  schema digests;\n• nextcursor, an opaque cursor when another page exists;\n• total, the total matches at that revision.\n\nThe bearer credential must be mapped to a tenant for this HTTP route. The\ncatalog returns only capabilities with an enabled binding for that tenant, an\nenabled connector instance, an active version, and an enabled connector type.\nAn optional --profile filter selects versions whose manifest advertises that\nprofile.\n\nCatalog visibility is admission evidence, not liveness evidence. The query\ndoes not require a ready replica. Route selection can still fail later if no\neligible host has a valid lease and available capacity.\n\nTo continue pagination, pass the exact nextcursor returned by the preceding\npage:\n\nexport NEXTCURSOR='paste-the-exact-nextcursor-value'\n\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token-file \"$AIPTOKENFILE\" \\\n  capability list \"$AIPURL\" \\\n  --cursor \"$NEXTCURSOR\" \\\n  --limit 50\n\nDo not combine a cursor with pages from another catalog revision. If the\nserver reports connectorcatalog.stalecursor, discard the old cursor and\nrestart from the first page.\n5. Check the selected contract\n\nBefore invoking a catalog capability, inspect its complete definition. At a\nminimum, record and evaluate:\n• the exact capability ID, contract digest, and schema digest;\n• the input and output schemas;\n• declared execution modes and streaming behavior;\n• side effects, risk, and human-approval requirements;\n• idempotency key requirements and scope;\n• transaction, reconciliation, cancellation, and compensation support;\n• credential and data boundaries;\n• profile bindings required by the client.\n\nDo not infer these properties from a display name. If the contract changed\nsince the caller last evaluated it, repeat the caller's policy and input\ndecision against the new revision before submitting work.\n6. Invoke without choosing a connector host\n\nPrepare the selected input as a JSON object and keep the identifiers outside\nthe file:\n\nexport AIPCAPABILITYID='cap:replace:with:catalog-id'\nexport AIPACTIONID='actreplacewithstableid001'\n\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token-file \"$AIPTOKENFILE\" \\\n  action call \"$AIPURL\" \\\n  \"$AIPCAPABILITYID\" \\\n  --action-id \"$AIPACTIONID\" \\\n  --input @request.json\n\nAdd --mode, --idempotency-key, approval, or transaction options only as\nrequired by the selected contract. For a replay-sensitive mutation, retain the\noriginal action ID, idempotency key, transaction ID, and plan ID together.\n\nDo not send an instance ID, replica ID, host URL, connector version, or\ncredential reference. The central runtime uses the verified execution tenant\nand capability ID to resolve an enabled binding. It persists an action-scoped\nroute before dispatch and sends a signed native AIP envelope to the assigned\nhost. The host then rechecks the pinned route and trusted gateway identity.\n\nThe client sees the ordinary AIP action lifecycle in both placements. A local\ncapability runs through its admitted in-process handler. A fleet capability\nruns through the remote handler, registry assignment, and connector host. A\nclient retry with the same action identity does not authorize choosing another\nprovider account or replica.\n7. Read or follow the durable action\n\nRead the current lifecycle view independently of the submission response:\n\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token-file \"$AIPTOKENFILE\" \\\n  action status \"$AIPURL\" \\\n  \"$AIPACTIONID\" \\\n  --include-result \\\n  --include-receipts\n\nFor long-running or streaming work, follow action-scoped events and chunks:\n\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token-file \"$AIPTOKENFILE\" \\\n  action events \"$AIPURL\" \\\n  \"$AIPACTIONID\" \\\n  --include-chunks \\\n  --follow\n\nPersist the last acknowledged cursor before reconnecting. A resumed consumer\nmust tolerate replay. A cursor orders the retained event view; it is not an\nexactly-once delivery token.\n\nIf the submission connection failed before a response, query the stable action\nID first. Retry only under the capability's idempotency and uncertainty rules,\nusing every original identity. Generating a new action ID creates a new logical\noperation and can permit another provider effect.\n8. Request cancellation\n\nRequest cancellation of the same durable action:\n\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token-file \"$AIPTOKENFILE\" \\\n  action cancel \"$AIPURL\" \\\n  \"$AIPACTIONID\" \\\n  --reason 'The requester withdrew the operation'\n\nFor a fleet action, cancellation uses the persisted route assignment rather\nthan resolving a new host. The runtime records cancellation intent, but a\nprovider mutation may already have completed or may not support remote\ncancellation. Query the action and any transaction or reconciliation state\nbefore deciding that another mutation is safe.\n9. Send a raw envelope when necessary\n\nUse the generic native message endpoint when implementing a client or testing\na message family without an ergonomic CLI command. Keep this example on the\nloopback endpoint from step 1:\n\nexport AIPURL=http://127.0.0.1:18080\nexport AIPTOKENFILE=.aip-native-token\n\nSave this example as action-envelope.json and replace sentat with the\ncurrent RFC 3339 time:\n\n{\n  \"aipversion\": \"1.0\",\n  \"messagetype\": \"aip.core.v1.action\",\n  \"messageid\": \"msgnativeguideraw0001\",\n  \"sentat\": \"2026-07-26T20:00:00Z\",\n  \"from\": {\n    \"id\": \"agent:getaip:cli\",\n    \"kind\": \"agent\"\n  },\n  \"body\": {\n    \"action\": {\n      \"id\": \"actnativeguideraw0001\",\n      \"capabilityid\": \"cap:aip:server:health\",\n      \"input\": {},\n      \"mode\": \"sync\"\n    }\n  }\n}\n\nLoad the development token without placing it literally in the command:\n\nAIPTOKEN=$(tr -d '\\r\\n' /dev/null\n\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token-file \"$AIPTOKENFILE\" \\\n  action status \"$AIPURL\" \\\n  actnativeguidehealth001 \\\n  --include-result >/dev/null\n\nBoth commands must exit with status 0. For a fleet capability, also confirm\nthat the terminal result belongs to the original action ID and that any\nrequired receipt, transaction, or reconciliation evidence is present. A\nsuccessful call demonstrates only the configured path and provider response;\nit is not connector qualification or a production-readiness claim.\n\nStop and clean up the loopback state\n\nStop the local daemon with Control-C. Keep .getaip-server-native-guide if you need to\nrestart the daemon and inspect the same action. When the local history and\ndevelopment credential are no longer needed, inspect and remove only those two\npaths:\n\ndu -sh .getaip-server-native-guide\nls -l .aip-native-token\nrm -rf -- .getaip-server-native-guide\nrm -- .aip-native-token\n\nDo not apply this cleanup to a shared endpoint, connector registry, provider,\nor retained qualification evidence.\n\nResolve common failures\n\n| Symptom | Meaning | Safe next action |\n\n| Native route returns 401 | Bearer credential is missing or invalid | Confirm the intended token file and endpoint; do not print the token |\n| Catalog returns connectorcatalog.disabled | This daemon has no connector catalog | Configure the registry data plane or use the endpoint's manifest for local capabilities |\n| Catalog returns connectorcatalog.tenantrequired | The bearer identity has no discovery tenant | Bind the intended static credential with --native-tenant-id; do not copy a tenant from request data |\n| Catalog returns connectorcatalog.stalecursor | The registry changed during pagination | Restart from the first page and evaluate the new revision |\n| Capability is absent | No visible enabled binding and active version matched the tenant and filters | Check the tenant binding, instance, version, type, filters, and catalog revision |\n| Remote execution reports that a verified tenant is required | Discovery identity was configured, but runtime identity enrichment did not establish execution tenant | Correct the trusted identity binding for the authenticated principal; do not rely on --native-tenant-id |\n| Invocation has no eligible replica | Admission was visible, but no ready route has valid lease, capacity, and policy | Preserve the action identity and ask the operator to restore or drain the fleet deliberately |\n| Client disconnected after submission | The durable action outcome is unknown to the client | Query the original action ID before any retry |\n| Cancellation returns but the provider may have changed state | Cancellation is intent, not proof of rollback | Inspect the terminal action, provider operation, transaction, and reconciliation evidence |\n\nRelated documentation\n• Complete the connector fleet quickstart (../getting-started/connector-fleet-quickstart.md)\n  to observe one deterministic remote path.\n• Read Capabilities and contracts (../concepts/capabilities.md) before choosing\n  modes, retries, or transaction options.\n• Read Actions and sessions (../concepts/actions-and-sessions.md) for lifecycle,\n  idempotency, events, and cancellation semantics.\n• Use the Native HTTP API (../reference/http-api.md) for exhaustive route and\n  query syntax.\n• Use Errors and retry decisions (../reference/errors.md) before automating\n  recovery.\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "aeba8ff08f8f0ff761b70b93c54e9633272486f0495b6636da535e9b5d2acc1d"
  }
}