# 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

```sh
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

```sh
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

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```json
{
  "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](../spec/AIP-1.0.md).

## Cancel Safely

```sh
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

- [Actions and Sessions](../concepts/actions-and-sessions.md)
- [Approvals and Policy](../concepts/approvals-and-policy.md)
- [Transactions and Compensation](../concepts/transactions-and-compensation.md)
- [Native HTTP API](../reference/http-api.md)
- [Errors and Retry Decisions](../reference/errors.md)