How AIP Works — AIP Documentation

AIP turns a request into a governed, observable unit of work. The protocol does not assume that work finishes in one HTTP response or that the caller and the system performing the work share the same technology stack.

The Request Path

sequenceDiagram
    participant C as Client or Agent
    participant G as AIP Gateway
    participant P as Policy and Identity
    participant R as Durable Runtime
    participant X as Connector or Native Handler

    C->>G: Discover manifest
    G-->>C: Capabilities and contracts
    C->>G: Action envelope
    G->>P: Authenticate and authorize
    P-->>G: Allow, deny, or require approval
    G->>R: Reserve action and idempotency key
    R->>X: Invoke with trusted execution context
    X-->>R: Chunks, result, or uncertain outcome
    R-->>C: Result, stream, or callback
    C->>G: Query status, events, receipts
    G-->>C: Durable operational view

1. Discovery

A participant publishes a manifest. Each capability includes an input schema and may include output, risk, side-effect, approval, idempotency, data, service level, transaction, and compensation contracts.

Discovery lets a caller answer two questions before sending work:

Can this participant perform the operation?
Under what safety and lifecycle conditions will it perform it?

2. Authentication and Trusted Context

An envelope may contain a from principal, but that field is a claim. The edge authenticates the transport identity and creates trusted execution context. AIP then resolves tenant membership, credential references, scopes, and delegated authority from server-controlled data.

Connectors receive this frozen context. They must not trust a tenant id, credential handle, or approver identity merely because it appeared in user input.

3. Action Admission

The gateway validates the envelope, capability contract, input schema, invocation mode, deadline, idempotency rules, and policy decision. Admission is atomic with the handler catalog: a manifest cannot advertise a callable capability unless an admitted handler owns it.

The runtime then reserves the action. Duplicate idempotency keys follow the capability’s declared collision policy; they are not treated as new work.

4. Execution

An action can be synchronous, asynchronous, or streaming.

Synchronous returns a final result in the request path.
Asynchronous returns acceptance and continues through a durable worker.
Streaming emits ordered chunks before a terminal result.

Cancellation is cooperative and capability-specific. The runtime records the request even when a provider cannot confirm cancellation immediately.

5. Human Approval

When policy requires approval, the runtime creates a durable approval request and parks the action. A trusted authority resolver verifies the approver and the applicable rule. An approved decision resumes the same governed action; the caller does not submit a replacement operation with different input.

6. Transactions

Sensitive mutations may use dry_run, plan, commit, compensate, or reconcile. A plan binds the capability, input hash, identity, policy, and transaction id. Commit is accepted only for the same immutable operation.

If a provider may have committed but the response was lost, the runtime records outcome_unknown. It reconciles provider state before retrying or compensating.

7. Delegation

Delegation creates a child action linked to a parent action. AIP carries the delegation scope and chain across the trust boundary, routes the request to an authenticated peer, and correlates the child’s result with the parent graph. The child is still a normal AIP action with policy, lifecycle, cancellation, events, and receipts.

8. Evidence and Recovery

The runtime stores lifecycle events, stream chunks, approval state, transactions, callback attempts, and receipt chains. Clients and operators use query APIs instead of inferring state from logs or retrying blindly.

This separation is central to AIP: the response tells a caller what happened in one exchange; the operational read model tells authorized readers what the system currently knows.