Skip to content
AIPDocs
AIP 1.055 pagesGuide
Release status
DocumentationAIP 1.0GuideBuild with AIP

Use Native AIP

Native AIP is the full-fidelity interface for clients that need durable actions, trusted identity, approvals, transactions, delegation, receipts, or operational queries without projecting them through another protocol.

This guide uses aipctl for normal work and raw HTTP only when the envelope itself matters.

Start a Local Authenticated Daemon

cargo run -p aipd -- \
  --bind 127.0.0.1:18080 \
  --service-id agent:aipd:native-guide \
  --native-bearer-token local-development-token \
  --native-principal agent:aipctl \
  --native-principal-scope action:read \
  --storage-dir .aipd-native-guide

This is a loopback development command. Use an owner-only token file or a deployment identity boundary outside local development.

Discover before Calling

cargo run -p aipctl -- \
  --native-bearer-token local-development-token \
  manifest fetch http://127.0.0.1:18080

Inspect the selected capability’s input schema, execution modes, side effects, idempotency requirement, approval policy, and transaction support. Do not infer these properties from the capability name.

Invoke a Synchronous Action

cargo run -p aipctl -- \
  --native-bearer-token local-development-token \
  action call http://127.0.0.1:18080 \
  cap:aipd:health \
  --mode sync \
  --input '{}'

Store the returned action_id. The HTTP response is not the durable source of truth after disconnect or restart.

Submit Long-Running Work

Request async mode only when the capability advertises it:

cargo run -p aipctl -- \
  --native-bearer-token "$AIP_TOKEN" \
  action call "$AIP_URL" cap:example:workflow \
  --mode async \
  --idempotency-key order-8842-workflow-v1 \
  --input @workflow-input.json

Then query or follow the same action:

cargo run -p aipctl -- \
  --native-bearer-token "$AIP_TOKEN" \
  action status "$AIP_URL" ACT_ID --include-result --include-receipts

cargo run -p aipctl -- \
  --native-bearer-token "$AIP_TOKEN" \
  action events "$AIP_URL" ACT_ID --include-chunks --follow

Persist the last event cursor before acknowledging downstream processing. Consumers must tolerate replay after reconnect.

Send a Raw Envelope

Use the generic message endpoint when implementing a native client or testing a message family not exposed as an ergonomic HTTP route:

curl --fail-with-body \
  -H 'Authorization: Bearer local-development-token' \
  -H 'Content-Type: application/aip+json' \
  --data @action-envelope.json \
  http://127.0.0.1:18080/aip/v1/messages

action-envelope.json contains a complete AIP envelope:

{
  "aip_version": "1.0",
  "message_type": "aip.core.v1.action",
  "message_id": "msg_native_guide_0001",
  "sent_at": "2026-07-14T12:00:00Z",
  "from": {
    "id": "agent:aipctl",
    "kind": "agent"
  },
  "body": {
    "action": {
      "id": "act_native_guide_0001",
      "capability_id": "cap:aipd:health",
      "input": {},
      "mode": "sync"
    }
  }
}

The authenticated edge is authoritative and replaces an untrusted from claim. Signed peer-to-peer traffic follows the signature and replay rules in the AIP 1.0 Specification.

Cancel Safely

cargo run -p aipctl -- \
  --native-bearer-token "$AIP_TOKEN" \
  action cancel "$AIP_URL" ACT_ID \
  --reason 'The requester withdrew the operation'

Cancellation intent is durable, but an external mutation may finish before the provider confirms cancellation. Query the terminal action and transaction state before deciding whether another operation is safe.

Next Steps