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

# End-to-End Flow

> Complete flows for both recommend and delegate modes  -  from PlatformRequest through every schema and event.

## Flow Overview

AIP connects AI Platforms, Operators, and Brand Agents through a series of request/response cycles, selection, and event verification. The protocol supports two distinct flows based on the interaction mode.

***

## Flow 1: Recommend Mode

Used when the user is researching, considering, or comparing options. The brand agent contributes to the AI response without any session transfer.

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Platform as AI Platform
    participant Operator as AIP Operator
    participant BrandAgent as Brand Agent

    User->>Platform: "Best accounting software for freelancers"
    Platform->>Operator: PlatformRequest
    Note over Platform,Operator: Contains: intent (commercial, consideration),<br/>runtime (query, session),<br/>selection params

    Operator->>Operator: Evaluate participation<br/>eligibility
    Note over Operator: Check intent type,<br/>governance rules

    Operator->>Operator: Derive ContextRequest
    Note over Operator: Remove raw user data,<br/>enrich with intent

    Operator->>BrandAgent: ContextRequest<br/>(privacy-preserving)
    Note over Operator,BrandAgent: Contains: intent, verticals,<br/>allowed_formats,<br/>latency_budget_ms

    BrandAgent->>BrandAgent: Evaluate and respond
    BrandAgent->>Operator: Response<br/>(with recommendation content)
    Note over BrandAgent,Operator: Contains: pricing,<br/>creative_input, declared_relevance

    Operator->>Operator: Run selection,<br/>determine mode: recommend
    Operator->>Platform: PlatformResponse<br/>(mode: recommend)
    Note over Operator,Platform: Contains: serve_token,<br/>format-specific content

    Platform->>User: AI integrates recommendation

    User->>User: Sees recommendation
    Platform->>Operator: exposure_shown event

    alt User engages
        User->>User: Clicks recommendation
        Platform->>Operator: interaction_started event

        alt User converts
        User->>User: Navigates to brand site and completes the target action
        BrandAgent->>Operator: task_completed event
        end
    end

    Operator->>Operator: Verify highest event,<br/>settle
```

### Recommend flow summary

1. User asks a question with commercial intent
2. Platform sends PlatformRequest to Operator
3. Operator evaluates participation eligibility  -  allowed
4. Operator derives ContextRequest and sends to eligible brand agents
5. Brand agents respond with pricing and content
6. Operator runs selection, determines recommend mode
7. Platform receives PlatformResponse and integrates recommendation into AI response
8. Events track the lifecycle: exposure\_shown → interaction\_started → task\_completed
9. Only the highest-value event is settled

***

## Flow 2: Delegate Mode

Used when the user has transactional intent and is ready to act. The AI hands off the session to a brand agent for task execution.

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Platform as AI Platform
    participant Operator as AIP Operator
    participant BrandAgent as Brand Agent

    User->>Platform: "Sign me up for QuickBooks"
    Platform->>Operator: PlatformRequest
    Note over Platform,Operator: Contains: intent (transactional, action),<br/>runtime (query, session)

    Operator->>Operator: Evaluate participation<br/>eligibility
    Note over Operator: Transactional intent,<br/>delegation allowed

    Operator->>Operator: Derive ContextRequest
    Operator->>BrandAgent: ContextRequest
    BrandAgent->>Operator: Response (with delegation capability)

    Operator->>Operator: Run selection,<br/>determine mode: delegate
    Operator->>Platform: PlatformResponse<br/>(mode: delegate, delegation object)
    Note over Operator,Platform: Contains: serve_token,<br/>delegation session_id,<br/>context_scope

    Platform->>User: "QuickBooks can handle your signup. Proceed?"
    User->>Platform: Confirms consent
    Platform->>Operator: Consent confirmed

    Operator->>BrandAgent: Check availability +<br/>initiate session
    BrandAgent->>Operator: Session accepted
    Note over Operator,BrandAgent: Only intent + constraints<br/>shared per context_scope

    Operator->>Operator: delegation_started recorded
    BrandAgent->>Platform: Delegated session ready
    Note over Platform,BrandAgent: After session start, live task turns may flow directly
    User->>Platform: Follow-up questions in delegated session
    Platform->>BrandAgent: Delegated task turns
    BrandAgent->>Platform: Delegated task responses
    Platform->>Operator: delegation_activity events
    BrandAgent->>Operator: delegation_activity events
    Note over Platform,BrandAgent: New task data is collected in-session and is session-bound by default

    User->>BrandAgent: Completes signup
    BrandAgent->>Operator: task_completed event
    Note over BrandAgent,Operator: outcome_type: signup

    Operator->>Operator: Verify outcome,<br/>settle CPA
```

### Delegate flow summary

1. User expresses transactional intent
2. Platform sends PlatformRequest to Operator
3. Operator evaluates eligibility  -  delegation is allowed
4. Operator derives ContextRequest and sends to eligible agents
5. Brand agent responds with delegation capability
6. Operator runs selection, determines delegate mode
7. Platform receives PlatformResponse with delegation object
8. Platform asks user for consent
9. User consents and the Platform sends that consent to the Operator
10. Operator confirms brand-agent availability, initiates the delegated session, and records `delegation_started`
11. Platform and Brand Agent continue the live delegated task flow after the operator-mediated start
12. Both Platform and Brand Agent emit `delegation_activity` while the session remains active
13. Any new information the user provides in-session is session-bound by default and not part of the original handoff scope
14. If no activity arrives before `session_timeout_seconds`, the Operator records `delegation_expired`
15. Brand agent executes the task
16. `task_completed` event fired and verified
17. Operator settles CPA

***

## 1. Platform Request (AI Platform → Operator)

**Schema:** [`platform-request.json`](/schemas/platform-request)

The AI platform initiates the process by sending a `PlatformRequest` to the operator. The operator validates the request, evaluates participation eligibility, and if eligible derives a **ContextRequest** and sends it to brand agents.

### Key fields:

* `spec_version`: AIP request schema version (e.g. "1.0")
* `message_id`: Canonical per-message identifier used for auction identity and replay
* `timestamp`: ISO 8601 timestamp
* `producer`: Producer information; **`agent_role` must be `"platform"`**
* `context`: Context (language, publisher, placement, device, geography)
* `identity`: Identity (namespace, value\_hash, confidence)
* `extensions.aip.intent`: **Required.** Platform-declared intent (domain, subdomain, confidence) for participation governance
* `extensions.aip.runtime`: **Required.** session\_id, turn\_index, query\_text, optional messages, latency\_budget\_ms
* `extensions.aip.selection`: Optional. pricing\_model, cpx\_floor, currency

### Example:

```json theme={null}
{
  "spec_version": "1.0",
  "message_id": "msg_92fA1_turn_003",
  "timestamp": "2025-11-14T18:22:00Z",
  "producer": {
    "agent_id": "openai_chat",
    "agent_role": "platform",
    "software": "chatgpt",
    "software_version": "4.3-mini"
  },
  "context": {
    "language": "en-US",
    "publisher": "openai_chat",
    "placement": { "unit": "conversation" },
    "device": { "platform": "web", "form_factor": "desktop", "ua_hash": "ua_hash_xyz" },
    "geography": { "country": "US" }
  },
  "identity": {
    "namespace": "platform_user",
    "value_hash": "user_hash_abc123",
    "confidence": 1.0
  },
  "extensions": {
    "aip": {
      "intent": { "domain": "business", "subdomain": "crm", "confidence": 0.91 },
      "runtime": {
        "session_id": "sess_001",
        "turn_index": 3,
        "query_text": "best CRM for small teams",
        "messages": [
          { "role": "user", "content": "best CRM tools?" },
          { "role": "assistant", "content": "HubSpot, Zoho, Salesforce…" }
        ],
        "latency_budget_ms": 500
      },
      "selection": { "pricing_model": "CPX", "cpx_floor": 0.05, "currency": "USD" }
    }
  }
}
```

***

## 2. Context Request (Operator → Brand Agents)

**Schema:** [`context-request.json`](/schemas/context-request)

The operator normalizes the platform request and enriches it with intent analysis, then sends a `ContextRequest` to brand agents.

### Key fields:

* `spec_version`: AIP specification version (default: "1.0")
* `context_id`: Unique identifier for this operator-generated ContextRequest
* `message_id`: Canonical upstream message identifier
* `timestamp`: ISO 8601 timestamp
* `operator`: Operator information
* `platform`: Upstream platform information
* `session.id`: Conversation or interaction session ID
* `session.turn_index`: Turn index in the conversation
* `language`: User locale in BCP 47 format
* `intent`: Operator-generated semantic understanding
  * `type`: "informational" | "commercial" | "transactional"
  * `decision_phase`: canonical decision phase enum
  * `confidence`: Confidence score (0.0-1.0)
  * `summary`: Short summary of conversation context
* `verticals`: Normalized topical verticals
* `allowed_formats`: Content formats allowed
* `latency_budget_ms`: Platform latency budget in milliseconds

### Example:

```json theme={null}
{
  "spec_version": "1.0",
  "context_id": "ctx_92fA1",
  "message_id": "msg_92fA1_turn_003",
  "timestamp": "2025-11-14T18:22:00Z",
  "operator": {
    "operator_id": "admesh_operator"
  },
  "platform": {
    "platform_id": "openai_chat",
    "software": {
      "name": "chatgpt",
      "version": "4.3-mini"
    }
  },
  "session": {
    "id": "sess_001",
    "turn_index": 3
  },
  "latency_budget_ms": 500,
  "allowed_formats": ["weave", "tail", "product_card"],
  "language": "en-US",
  "intent": {
    "type": "commercial",
    "decision_phase": "consideration",
    "confidence": 0.87,
    "summary": "User is evaluating CRM tools and narrowing down options."
  },
  "verticals": ["crm", "smb_software"]
}
```

***

## Selection window and timing

AIP uses a time-bounded selection window to ensure low latency and predictable outcomes.

* The selection window is derived from the PlatformRequest `latency_budget_ms` field
* The Operator computes the available response window by subtracting operator overhead from the platform's latency budget
* The window begins when the ContextRequest is published
* Brand agents MUST submit responses before the computed window expires
* If `latency_budget_ms` is not provided, the Operator MUST apply a default fallback

If the window expires with no responses, the outcome is `no_match`. Late responses are ignored.

***

## 3. Brand Agent Response (Brand Agents → Operator)

**Schema:** [`bid.json`](/schemas/bid)

Brand agents evaluate the context request and submit `Bid` payloads containing pricing, targeting, budget, and structured recommendation content.

### Key fields:

* `spec_version`: Schema version for the bid payload
* `bid_id`: Unique identifier for this bid
* `brand_agent_id`: Identifier of the brand agent
* `context_id`: ID of the ContextRequest being responded to
* `wallet_id`: Wallet to debit if selected
* `targeting`: Applicability constraints for the bid
* `pricing`: Pricing fields in micros
* `budget`: Spend caps and pacing controls
* `recommendation.creative_input`: Unified content structure
* `declared_relevance`: Relevance score (0.0-1.0, required)
* `delegation`: Delegation capability declaration (optional)
* `valid_until`: Bid expiry timestamp

### Example:

```json theme={null}
{
  "spec_version": "1.0",
  "bid_id": "bid_7823",
  "brand_agent_id": "brand_agent_123",
  "context_id": "ctx_92f",
  "wallet_id": "wallet_890",
  "targeting": {
    "intent_types": ["commercial", "transactional"],
    "decision_phases": ["consideration", "decision"],
    "verticals": ["crm", "sales_software"],
    "countries": ["US"],
    "locales": ["en-US"]
  },
  "pricing": {
    "currency": "USD",
    "cpx_micros": 50000,
    "cpc_micros": 450000,
    "cpe_micros": 700000,
    "cpa_micros": 10000000,
    "preferred_pricing_model": "CPA"
  },
  "budget": {
    "max_bid_per_event_micros": 10000000,
    "daily_cap_micros": 50000000,
    "remaining_budget_micros": 32000000,
    "pacing_mode": "even"
  },
  "recommendation": {
    "creative_input": {
      "brand_name": "Nimbus",
      "product_name": "Nimbus CRM Pro",
      "short_description": "CRM built for growing teams, with AI-assisted workflows.",
      "long_description": "Nimbus CRM Pro is designed for teams of 5-50 people who need intelligent pipeline management.",
      "value_props": [
        "Automated pipeline insights",
        "Collaborative forecasting"
      ],
      "context_snippet": "For startups needing higher limits and automated expense workflows.",
      "cta_label": "Start Free Trial",
      "cta_url": "https://nimbus.example.com/signup"
    }
  },
  "supported_opportunities": ["comparison_slot", "decision_moment", "transaction_trigger"],
  "preferred_format": "weave",
  "format_constraints": {
    "max_responses": 1,
    "ranking": "operator_defined"
  },
  "valid_until": "2025-11-11T18:05:00Z",
  "timestamp": "2025-11-11T18:00:01Z",
  "declared_relevance": 0.87,
  "delegation": {
    "supported": true,
    "consent_required": true,
    "supported_for_intents": {
      "intent_types": ["transactional", "commercial"],
      "decision_phases": ["decision", "post_purchase"]
    },
    "required_scopes": ["intent", "constraints"],
    "protocol": {
      "type": "mcp",
      "version": "1.0"
    },
    "mcp": {
      "server_url": "https://agent.nimbus.example.com/mcp",
      "tool_name": "start_crm_signup_session",
      "session_init_schema_ref": "https://agent.nimbus.example.com/schemas/session-init.json"
    },
    "session_constraints": {
      "multi_turn": true,
      "session_timeout_seconds": 900,
      "max_turns": 20
    }
  }
}
```

***

## 4. PlatformResponse (Operator → AI Platform)

The operator evaluates the auction and returns a `PlatformResponse` to the AI platform.

### Key fields:

* `response_id`: Unique identifier for this response
* `auction_id`: Auction identifier
* `serve_token`: Token used to track downstream events
* `status`: Outcome status (`filled`, `no_match`, `error`)
* `winner`: Winning bid state, pricing, and billing reservation
* `render`: Structured render payload for platform presentation
* `delegation`: Optional delegation availability for the winning bid
* `ttl_ms`: Time-to-live in milliseconds

### Example (recommend mode):

```json theme={null}
{
  "spec_version": "1.0",
  "response_id": "resp_981",
  "auction_id": "auc_981",
  "serve_token": "stk_abcxyz123",
  "timestamp": "2026-03-26T18:00:02Z",
  "status": "filled",
  "winner": {
    "bid_id": "bid_7823",
    "brand_agent_id": "ba_451",
    "pricing": {
      "model": "CPA",
      "price_micros": 10000000,
      "currency": "USD"
    },
    "billing": {
      "reserved_amount_micros": 500000000,
      "currency": "USD"
    }
  },
  "render": {
    "format": "weave",
    "disclosure": "[Ad]",
    "creative": {
      "advertiser": {
        "brand_name": "Nimbus"
      },
      "ad_assets": {
        "headline": "Scale your CRM",
        "description": "Built for founders.",
        "cta_text": "Try for free"
      },
      "landing_page_url": "https://nimbus.example.com/signup",
      "click_url": "https://admesh.click/stk_abcxyz123"
    }
  },
  "delegation": {
    "available": true,
    "mode": "optional",
    "trigger": "user_action",
    "cta_text": "Continue with Nimbus"
  },
  "ttl_ms": 60000
}
```

***

## 5. Events (Platform / Operator / Brand Agent → Operator)

After participation begins, events track the decision lifecycle.

### 5.1 Exposure shown

Sent when the user sees the recommendation or delegation offer.

```json theme={null}
{
  "event_type": "exposure_shown",
  "serve_token": "stk_abcxyz123",
  "session_id": "sess_001",
  "platform_id": "openai_chat",
  "agent_id": "ba_451",
  "wallet_id": "w_0021",
  "settlement": {
    "unit": "CPX",
    "amount_micros": 34000,
    "currency": "USD"
  },
  "ts": "2025-11-14T18:22:05Z"
}
```

### 5.2 Interaction started

Sent when the user engages with the recommendation.

```json theme={null}
{
  "event_type": "interaction_started",
  "serve_token": "stk_abcxyz123",
  "session_id": "sess_001",
  "platform_id": "openai_chat",
  "agent_id": "ba_451",
  "wallet_id": "w_0021",
  "settlement": {
    "unit": "CPC",
    "amount_micros": 450000,
    "currency": "USD"
  },
  "interaction_metadata": {
    "source": "deep_link",
    "position": 1
  },
  "ts": "2025-11-14T18:22:10Z"
}
```

### 5.3 Delegation started

Sent by the Operator after the Platform has collected consent and the Operator has confirmed brand-agent availability and initiated the delegated session (delegate mode only).

This event proves session initiation and authorization. It does not imply that every subsequent delegated turn is transported through the Operator.

```json theme={null}
{
  "event_type": "delegation_started",
  "serve_token": "stk_abcxyz123",
  "session_id": "sess_001",
  "platform_id": "openai_chat",
  "agent_id": "ba_451",
  "delegation_session_id": "del_sess_001",
  "ts": "2025-11-14T18:22:15Z"
}
```

### 5.4 Delegation activity

Sent by the Platform or Brand Agent while the delegated session is still active. Each verified `delegation_activity` resets the inactivity timer for the session.

```json theme={null}
{
  "event_type": "delegation_activity",
  "serve_token": "stk_abcxyz123",
  "session_id": "sess_001",
  "platform_id": "openai_chat",
  "agent_id": "ba_451",
  "delegation_session_id": "del_sess_001",
  "actor_role": "platform",
  "activity_type": "user_turn",
  "activity_metadata": {
    "turn_index": 2
  },
  "ts": "2025-11-14T18:25:00Z"
}
```

### 5.5 Delegation expired

Sent by the Operator when the delegated session expires before completion, typically because the inactivity timeout elapsed.

```json theme={null}
{
  "event_type": "delegation_expired",
  "serve_token": "stk_abcxyz123",
  "session_id": "sess_001",
  "platform_id": "openai_chat",
  "agent_id": "ba_451",
  "delegation_session_id": "del_sess_001",
  "reason": "inactivity_timeout",
  "ts": "2025-11-14T18:40:00Z"
}
```

### 5.6 Task completed

Sent when the user completes the target action.

```json theme={null}
{
  "event_type": "task_completed",
  "serve_token": "stk_abcxyz123",
  "session_id": "sess_001",
  "platform_id": "openai_chat",
  "agent_id": "ba_451",
  "wallet_id": "w_0021",
  "outcome_type": "signup",
  "outcome_value_micros": 0,
  "settlement": {
    "unit": "CPA",
    "amount_micros": 10000000,
    "currency": "USD"
  },
  "ts": "2025-11-14T18:25:00Z"
}
```

***

## Schema relationships

| Schema             | Used In                 | Purpose                           |
| ------------------ | ----------------------- | --------------------------------- |
| `platform-request` | AI Platform → Operator  | Initial participation request     |
| `context-request`  | Operator → Brand Agents | Eligible participation context    |
| `bid`              | Brand Agents → Operator | Response with pricing and content |
| `PlatformResponse` | Operator → AI Platform  | Selected agent + interaction mode |

***

## Key identifiers flow

```
message_id (PlatformRequest)
    ↓
context_id (ContextRequest) ← derived from session_id + message_id
    ↓
bid_id (Bid) ← references context_id
    ↓
response_id (PlatformResponse)
    ↓
auction_id (PlatformResponse)
    ↓
serve_token (PlatformResponse) ← used in all events
    ↓
event_id (Events) ← references serve_token
    ↓
ledger_id (Settlement record) ← references event_id, bid_id, auction_id
```

***

## Common patterns

### Authentication

All requests include an `auth` object with:

* `nonce`: One-time nonce for replay protection
* `sig` or `signature`: HMAC signature of the request

### Timestamps

All timestamps use ISO 8601 / RFC 3339 format:

* Format: `YYYY-MM-DDTHH:mm:ssZ`
* Example: `2025-11-14T18:22:00Z`

### Money/Currency

* Monetary values in events and settlement use integer micros
* Currency: ISO 4217 code (e.g., `"USD"`)

### IDs

* Platform-generated: `req_*`, `sess_*`, `user_*`
* Operator-generated: `ctx_*`, `auc_*`, `resp_*`, `stk_*`
* Brand Agent-generated: `bid_*`
* Event-generated: `evt_*`
* System-generated: `ledger_*`, `wallet_*`