> ## Documentation Index
> Fetch the complete documentation index at: https://www.agentcommercekit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> High-level architecture of ACK roles and interaction patterns.

The ACK architecture provides a modular framework designed to facilitate secure, verifiable, and compliant interactions among autonomous agents, human participants, and networked resources. ACK combines identity verification (ACK-ID), transactional integrity (ACK-Pay), and flexible human oversight into a cohesive, interoperable ecosystem.

## Roles

ACK defines several functional roles that can be implemented flexibly, depending on specific use cases and organizational needs:

| Role                   | Description                                                                                                                                                                                                               |
| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Client Agent**       | Systems initiating service requests or payments on behalf of end-users or autonomous processes (e.g., applications, other agents).                                                                                        |
| **Server Agent**       | Systems delivering services/resources, verifying identities (ACK-ID) and receipts (ACK-Pay), and fulfilling requests (e.g., APIs, service agents, MCP providers).                                                         |
| **Identity Provider**  | Services issuing and verifying identity credentials (DIDs/VCs via ACK-ID) to establish trust.                                                                                                                             |
| **Payment Service**    | Manages ACK-Pay payment execution, acting as an intermediary handling settlement, compliance, conversions, and human oversight flows. Payment Services may be implemented as agents, or as API services exposed by tools. |
| **Receipt Service**    | Issues and validates cryptographically verifiable ACK Receipts (as Verifiable Credentials) upon payment confirmation.                                                                                                     |
| **Settlement Network** | Underlying financial infrastructures processing value transfer (e.g., banking rails, card networks, blockchains).                                                                                                         |

<Info>
  Organizations implementing ACK may map these roles flexibly. Multiple roles
  might be combined into a single service, or roles might be distributed across
  specialized components.
</Info>

## Core Interaction Patterns

ACK outlines two primary interaction patterns: **Server-Initiated** and **Client-Initiated** sequences. Both patterns leverage the Payment Service to handle the complexities of payment execution and utilize the standardized ACK Receipt as verifiable proof.

<CardGroup cols={2}>
  <Card title="Server-Initiated Sequence" href="#server-initiated-sequence">
    This pattern is typically used when a Server Agent requires payment before
    fulfilling a Client Agent's request for a resource or service.
  </Card>

  <Card title="Client-Initiated Sequence" href="#client-initiated-sequence">
    This pattern is used when a Client Agent initiates a payment based on a
    known out-of-band obligation (e.g., paying an invoice or completing an
    e-commerce checkout).
  </Card>
</CardGroup>

### Server-Initiated Sequence

Below is an overview of the Server-Initiated Sequence:

```mermaid theme={null}
%%{ init: { 'theme': 'mc', 'themeVariables': { 'primaryColor': '#1D4ED8', 'lineColor': '#374151', 'textColor': '#1f2937', 'sequenceMessageAlign': 'center' } } }%%
sequenceDiagram;
    participant CA as Client Agent;
    participant SA as Server Agent;
    participant PS as Payment Service;
    participant RS as Receipt Service;
    participant SN as Settlement Network;

    CA->>SA: 1: Request Resource;

    rect rgba(0, 0, 255, .03)
        SA-->>CA: Request Proof of Agency;
        CA-->>SA: Present Identity Proof;
        Note right of SA: Verify Client Identity;
    end

    SA->>CA: 2: Payment Request;

    rect rgba(0, 0, 255, .03)
        CA-->>SA: Request Proof of Agency;
        SA-->>CA: Present Identity Proof;
        Note right of CA: Verify Server Identity;
    end

    CA->>PS: 3: Initiate Payment;

    rect rgba(0, 0, 255, .03)
        PS-->>CA: Request Proof of Agency;
        CA-->>PS: Present Identity Proof & Request Server Proof of Agency;
        Note right of PS: Verify Client Identity;
        PS-->>CA: Present Identity Proof;
        Note right of CA: Verify Payment Service Identity;
    end

    PS<<-->>CA: Potential human-in-the-loop approvals
    PS->>SN: 4: Execute/Settle;
    %% Note: Settlement confirmation back to PS is implied %%
    PS->>RS: 5: Request Receipt;
    RS-->>PS: Issue Receipt (VC);
    PS-->>SA: Deliver receipt via optional callback
    PS->>CA: 6: Deliver Receipt;
    CA->>SA: 7: Present Receipt;
    SA-->>SA: Verify Receipt;
    %% Note: Verification uses VC crypto & issuer's public info, NO callback to RS needed %%
    SA->>CA: 8: Deliver Resource;

```

*To enlarge this mermaid markdown diagram, zoom in on your browser (CMD +)*

<Steps>
  <Step title="Client Request & Optional Identity Verification">
    Client Agent requests a service/resource from the Server Agent. The Server
    Agent may optionally verify the Client's identity (requesting Proof of
    Agency) before replying.
  </Step>

  <Step title="Server Sends Payment Request & Optional Identity Verification">
    Server Agent determines payment is needed and sends a standardized ACK-Pay
    Payment Request payload to the Client (idiomatically via HTTP 402, or
    embedded in other protocols). The Client Agent optionally verifies the
    identity of the Server Agent.
  </Step>

  <Step title="Client Interacts with Payment Service">
    Client Agent selects a payment option from the Payment Request and interacts
    with the designated Payment Service. This interaction may involve optional
    mutual Proof of Agency between the Client and Payment Service, or additional
    requirements based upon various risk triggers. Human-in-the-loop approvals
    may occur at this stage.
  </Step>

  <Step title="Payment Execution by Payment Service">
    Payment Service executes the payment. This may include currency conversions,
    compliance checks, or additional internal approvals.
  </Step>

  <Step title="Receipt Generation & Optional Server Callback">
    Payment Service confirms successful payment and coordinates with the Receipt
    Service to request a verifiable ACK Receipt (as a Verifiable Credential). If
    a callback URL was included in the original Payment Request, the Payment
    Service transmits the Receipt to the Server Agent via the callback.
  </Step>

  <Step title="Receipt Delivery to Client">
    Payment Service returns the ACK Receipt to the Client Agent.
  </Step>

  <Step title="Client Presents Receipt to Server">
    Client Agent presents the ACK Receipt to the Server Agent (typically when
    re-requesting the resource or in a follow-up interaction). This may not be
    necessary if a Server callback occurs.
  </Step>

  <Step title="Server Verifies Receipt & Delivers Service">
    Server Agent verifies the ACK Receipt (cryptographically, and against its
    policies) and, if valid, delivers the requested service/resource.
  </Step>
</Steps>

### Client-Initiated Sequence

Below is an overview of the Client-Initiated Sequence:

```mermaid theme={null}

%%{ init: { 'theme': 'mc', 'sequenceMessageAlign': 'center' } }%%
sequenceDiagram;
    participant CA as Client Agent;
    participant PS as Payment Service;
    participant RS as Receipt Service;
    participant SN as Settlement Network;
    participant SA as Server Agent;

    Note right of CA: Identify Obligation <br/> (e.g., from invoice, chat instruction, web page scrape);
    CA<<->>CA: 1: Compose Payment Request;

    CA-->>PS: 2: Initiate Payment, Provide Identity Proof, Request Server Proof of Agency;

    rect rgba(0, 0, 255, .03)
        Note right of PS: Verify Client Identity;
        PS-->>CA: Present Identity Proof;
        Note right of CA: Verify Payment Service Identity;
        CA<<-->>PS: Payment Request Composition (if needed);
    end

    CA->>PS: 3: Initiate Payment;

    PS<<-->>CA: Potential human-in-the-loop approvals;
    PS->>SN: 4: Execute/Settle Payment;
    PS->>RS: 5: Request Receipt for Confirmed Payment;
    RS-->>PS: Issue Receipt (VC);
    PS-->>SA: Deliver Receipt via Optional Callback;
    PS->>CA: 6: Deliver Receipt;
```

*To enlarge this mermaid markdown diagram, zoom in on your browser (CMD +)*

<Steps>
  <Step title="Identify Obligation & Construct Payment Request">
    Client Agent identifies the payment obligation (recipient, amount, currency,
    reference). The Client Agent then constructs a structured Payment Request
    payload, potentially using a Payment Service API for assistance (e.g., to
    parse an invoice, a shopping cart summary, or interpret an end-user's
    instruction).
  </Step>

  <Step title="Select Payment Service & Initiate Payment">
    Client Agent selects/identifies an appropriate Payment Service (which may be
    pre-configured or dynamically discovered). The Client Agent provides its
    identity proof to the Payment Service.
  </Step>

  <Step title="Authorize Payment & Optional Identity Verification">
    Client Agent interacts directly with the Payment Service's API to authorize
    the payment. This interaction may involve optional mutual Proof of Agency
    between the Client and Payment Service, or additional requirements based
    upon various risk triggers. Human-in-the-loop approvals may occur here.
  </Step>

  <Step title="Payment Execution by Payment Service">
    Payment Service executes the payment. This may include currency conversions,
    compliance checks, or additional internal approvals.
  </Step>

  <Step title="Receipt Generation & Optional Server Callback">
    Payment Service confirms successful payment and coordinates with the Receipt
    Service to request a verifiable ACK Receipt (as a Verifiable Credential). If
    a callback was included in the Client's constructed Payment Request (or if
    the Payment Service knows the ultimate recipient Server), the Payment
    Service may transmit the Receipt to that Server Agent via a callback URL.
  </Step>

  <Step title="Receipt Delivery to Client & Optional Notification">
    Payment Service returns the ACK Receipt to the Client Agent. The Client
    Agent may then optionally inform the original recipient Server (if no
    callback occurred) or simply persist the receipt for its own records and
    auditing.
  </Step>
</Steps>

## Human-in-the-Loop Integration

ACK incorporates strategic human oversight at distinct levels:

* **Operational Oversight:** Payment Services provide hooks for internal approval workflows, risk monitoring, and exception handling processes to ensure compliance and transaction integrity in accordance with organizational policy (e.g., manual review of high-value or suspicious transactions).
* **User/Owner Authorization:** Client applications or agents may require explicit end-user or owner approvals for sensitive operations (e.g., confirming payments beyond a defined policy threshold), ensuring control and transparency.

Human judgment integration points are further illustrated in the ACK-Pay specification, allowing intervention based on risk profiles, transaction values, or specific policy conditions.

## Implementation Flexibility

ACK is a pattern framework rather than a mandated technology stack. Organizations can implement the ACK protocols and patterns using preferred technologies and frameworks. ACK remains technology-agnostic, emphasizing interoperability through message formats (like the Payment Request payload and ACK Receipt VC), verification standards, and flexible interaction patterns.

Agent discovery mechanisms are similarly flexible, with Clients able to discover Servers or Payment Services through direct configuration, public directories, specialized discovery services, or dynamic negotiation processes. ACK does not prescribe discovery or registry solutions, allowing integration with diverse existing and future discovery mechanisms.

This architectural framework provides the foundation for the specific identity (ACK-ID) and payment (ACK-Pay) protocols detailed in subsequent sections, enabling the secure and flexible agent interactions described.