### User Initiates Profile Setup Conversation

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-03-data-request/sample-flows.md

An example of a user's initial message to an agent, expressing their intent to set up a profile.

```text
User: I'd like to set up my profile.
```

--------------------------------

### Visualize Decision Type UI Examples with Mermaid

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-02-decisions/implementation-guide.md

This Mermaid diagram illustrates various UI patterns for decision types, including Radio, Checkbox, Confirmation, and Product selection. It shows their structure and flow, highlighting how user selections lead to responses, and applies distinct styling to each decision type for clarity.

```mermaid
graph TD
    subgraph "Decision Type UI Examples"
    
    subgraph "Radio"
        R1[Option 1] --> |Select One| RR[Radio Response]
        R2[Option 2] --> |Select One| RR
        R3[Option 3] --> |Select One| RR
    end
    
    subgraph "Checkbox"
        C1[Option 1] --> |Select Multiple| CR[Checkbox Response]
        C2[Option 2] --> |Select Multiple| CR
        C3[Option 3] --> |Select Multiple| CR
    end
    
    subgraph "Confirmation"
        CONF1[Yes] --> |Confirm Action| CONFR[Confirmation Response]
        CONF2[No] --> |Decline Action| CONFR
    end
    
    subgraph "Products"
        P1[Product Card 1] --> |Select Products| PR[Products Response]
        P2[Product Card 2] --> |Select Products| PR
        P3[Product Card 3] --> |Select Products| PR
        
        P1 --> |Has| P1IMG[Image]
        P1 --> |Has| P1DESC[Description]
        P1 --> |Has| P1PRICE[Price]
        P1 --> |Has| P1RATING[Rating]
        P1 --> |May Have| P1VAR[Variants]
    end
    
    end
    
    style Radio fill:#e3f2fd,stroke:#1976d2
    style Checkbox fill:#e8f5e9,stroke:#388e3c
    style Confirmation fill:#fff3e0,stroke:#e65100
    style Products fill:#f3e5f5,stroke:#7b1fa2
```

--------------------------------

### Install AITP Python Package

Source: https://github.com/nearai/aitp/blob/main/packages/aitp-py/README.md

This command installs the AITP Python package from PyPI using pip, making it available for import and use in Python applications.

```bash
pip install aitp
```

--------------------------------

### User Initiates Checkout Process

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-03-data-request/sample-flows.md

An example of a user's message indicating their readiness to proceed with a purchase and checkout.

```text
User: I'd like to checkout and complete my purchase.
```

--------------------------------

### Agent Confirms Profile Setup

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-03-data-request/sample-flows.md

The agent's conversational response confirming the successful creation of the user's profile, summarizing the collected information.

```text
Agent: Thanks, Jane! Your profile has been set up successfully. Your contact email is jane.smith@example.com and phone number is +1 555-123-4567. You can update this information anytime.
```

--------------------------------

### Example AITP-01 Payment Request JSON Schema

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-01-payments/aitp-01-payments.md

A JSON example demonstrating a payment quote structure within the AITP-01 protocol. It includes details such as quote ID, merchant, description, expiration, next recipient, payment options (amount, currency, method, token, recipient), and revenue sharing for affiliates.

```json
{
  "$schema": "https://aitp.dev/capabilities/aitp-01-payments/v0.1.0/schema.json",
  "quote": {
    "quote_id": "q_123456789",
    "merchant_id": "store.near",
    "description": "Premium Subscription - Annual Plan",
    "expiration": "2025-03-01T12:00:00Z",
    "next_recipient": "service-agent.near",
    "payment_options": [
      {
        "amount": "99.99",
        "currency": "USD",
        "payment_methods": [
          {
            "type": "near_payment_channel",
            "token": "usdc.near",
            "recipient": "store.near"
          }
        ]
      }
    ],
    "revenue_share": {
      "affiliate_share_bps": 300, // 3% in basis points
      "affiliates": [
        {
          "id": "assistant.near",
          "role": "personal_assistant",
          "weight": 2
        },
        {
          "id": "discovery.near",
          "role": "discovery",
          "weight": 1
        }
      ]
    },
    "merchant_signature": "ed25519:..."
  }
}
```

--------------------------------

### User-Agent Interaction Flow with AITP

Source: https://github.com/nearai/aitp/blob/main/website/docs/examples.md

A sequence diagram illustrating the interaction flow between a User Agent and a Shopping Agent using the AITP protocol. It depicts the exchange of requests, product options, decisions, payment quotes, and confirmations.

```mermaid
sequenceDiagram
    participant U as User Agent
    participant S as Shopping Agent
    
    U->>S: "I'd like to buy some socks"
    S->>U: request_decision JSON (product options)
    Note right of S: Shows options for red socks and blue socks<br>with prices, images, etc.
    U->>S: decision JSON (selects product)
    S->>U: payment quote JSON
    Note right of S: Quote for the selected product
    U->>S: approval/payment JSON
    S->>U: "Thank you for your purchase!"
    Note right of S: Order confirmation and next steps
```

--------------------------------

### Example AITP-01 Wrapped Quote Message

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-01-payments/schema-reference.md

A JSON example illustrating the structure of a wrapped quote message. This allows agents to add themselves and other affiliates to a payment request while forwarding it, maintaining a chain of responsibility.

```json
{
  "$schema": "https://aitp.dev/capabilities/aitp-01-payments/v1.0.0/schema.json",
  "wrapped_quote": {
    "original_quote": {
      "quote_id": "q_123456789",
      "merchant_id": "store.near",
      "description": "Premium Subscription - Annual Plan",
      "expiration": "2025-03-01T12:00:00Z",
      "next_recipient": "service-agent.near",
      "payment_options": [
        {
          "amount": "99.99",
          "currency": "USD",
          "payment_methods": [
            {
              "type": "near_payment_channel",
              "token": "usdc.near",
              "recipient": "store.near"
            }
          ]
        }
      ],
      "revenue_share": {
        "affiliate_share_bps": 300,
        "affiliates": []
      },
      "merchant_signature": "ed25519:..."
    },
    "wrappers": [
      {
        "affiliate_id": "service-agent.near",
        "role": "service",
        "added_affiliates": [],
        "next_recipient": "assistant.near",
        "timestamp": "2025-02-25T08:29:15Z",
        "signature": "ed25519:..."
      },
      {
        "affiliate_id": "assistant.near",
        "role": "personal_assistant",
        "added_affiliates": [
          {
            "id": "discovery.near",
            "role": "discovery",
            "weight": 1
          }
        ],
        "next_recipient": "user-interface.near",
        "timestamp": "2025-02-25T08:30:15Z",
        "signature": "ed25519:..."
      }
    ]
  }
}
```

--------------------------------

### JavaScript Pseudocode for Signing a Wrapped Quote

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-01-payments/schema-reference.md

Example pseudocode demonstrating the programmatic implementation of the wrapper signing process. It illustrates how to construct the payload, canonicalize the JSON, and apply cryptographic signing.

```javascript
// Example pseudocode for signing a wrapper
function signWrapper(originalQuote, previousWrappers, newWrapper, privateKey) {
  // Create a copy of the wrapper without the signature field
  const wrapperToSign = {...newWrapper};
  delete wrapperToSign.signature;
  
  // Create the payload that includes the original quote and all previous wrappers
  const payload = {
    original_quote: originalQuote,
    previous_wrappers: previousWrappers,
    new_wrapper: wrapperToSign
  };
  
  // Create canonical JSON (sorted keys, no whitespace)
  const canonicalJson = JSON.stringify(payload, Object.keys(payload).sort());
  
  // Sign the UTF-8 encoded canonical JSON
  const signature = ed25519Sign(privateKey, utf8Encode(canonicalJson));
  
  // Return the formatted signature
  return `ed25519:${base64Encode(signature)}`;
}
```

--------------------------------

### AITP-03 Data Request Capability Sequence Diagram

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-03-data-request/implementation-guide.md

This sequence diagram visualizes the end-to-end flow for the AITP-03 Data Request capability, detailing interactions between the User, Client UI, Agent, and Service Backend from initial service request to final confirmation.

```mermaid
sequenceDiagram
    participant U as User
    participant C as Client UI
    participant A as Agent
    participant S as Service Backend
    
    U->>A: Request service/information
    A->>A: Determine data requirements
    A->>C: request_data message
    Note over C: Form rendering
    C->>U: Display form UI
    U->>C: Fill out form
    C->>C: Validate input
    C->>A: data message with form values
    A->>S: Process form data
    S->>A: Operation result
    A->>U: Confirmation & next steps
```

--------------------------------

### Agent-User Decision Flow Diagram

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-02-decisions/implementation-guide.md

Illustrates the sequence of interactions between a user and an agent for the AITP-02 Decisions capability, from the initial natural language request to the agent processing the user's selection and providing confirmation.

```mermaid
sequenceDiagram
    participant U as User
    participant A as Agent
    
    U->>A: Natural language request
    A->>A: Determine need for structured decision
    A->>U: request_decision message
    Note over U,A: User interacts with UI elements
    U->>A: decision message
    A->>A: Process selection
    A->>U: Confirmation or next steps
```

--------------------------------

### AITP Overview JSON Structure

Source: https://github.com/nearai/aitp/blob/main/website/docs/examples.md

This JSON structure provides an overview of agents participating in an AITP interaction, detailing their unique IDs and declared capabilities. It also includes example message exchanges, showcasing the roles of actors and the content of their communications, including capability schemas.

```json
{
  "agents": [
    {"id": "root.near", "capabilities": [
      {""$schema": "https://aitp.dev/capabilities/aitp-01-payments/v0.1.0/schema.json"},
      {""$schema": "https://aitp.dev/capabilities/aitp-02-decisions/v1.0.0/schema.json"}
    ]},
    {"id": "hub.near.ai/travel-agent/0.1.0", "capabilities": [
      {""$schema": "https://aitp.dev/capabilities/aitp-01-payments/v0.1.0/schema.json" }
    ]}
  ],
  "messages": [
    {"metadata": {"actor": "root.near"},
      "content": ["plan me a trip to NY"],
      "role":  "user"},
    ...
    {"metadata": {"actor": "hub.near.ai/travel-agent/0.1.0"},
      "content": ["{\"$schema\": \"https://aitp.dev/capabilities/aitp-01-payments/v0.1.0/schema.json\", \"quote\": {...}}"],
      "role":  "assistant"},
    {"metadata": {"actor": "root.near"},
      "content": ["{\"$schema\": \"https://aitp.dev/capabilities/aitp-01-payments/v0.1.0/schema.json\", \"payment\": {...}}"],
      "role":  "user"}
  ]
}
```

--------------------------------

### User Initiates Conference Registration

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-03-data-request/sample-flows.md

A simple text snippet showing a user's initial prompt to an agent to begin the conference registration process. This demonstrates the conversational starting point for a multi-stage form interaction.

```text
User: I'd like to register for the conference.
```

--------------------------------

### Example: Simple Radio Selection Response

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-02-decisions/aitp-02-decisions.md

A practical example of a `decision` message responding to the simple radio selection request. It indicates that option '7' was selected by the user, referencing the original request ID.

```json
{
  "$schema": "https://aitp.dev/capabilities/aitp-02-decisions/v1.0.0/schema.json",
  "decision": {
    "request_decision_id": "7c42b9d6-107d-4f5f-8f23-f9014c6efdae",
    "options": [
      { "id": "7", "name": "7" }
    ]
  }
}
```

--------------------------------

### Create AITP Thread JSON Request

Source: https://github.com/nearai/aitp/blob/main/website/docs/examples.md

This JSON payload demonstrates how to create a new AITP thread. It specifies a unique thread ID and includes metadata such as a parent thread ID and a list of participating actors, each with their declared AITP capabilities.

```json
{
  "id": "thread_travel-agent-1",
  "metadata": {
    "parent_id": "thread_7518075837403837",
    "actors": "[{\"id\": \"root.near\", \"capabilities\": [{\"$schema\": \"https://aitp.dev/v1/payments.schema.json\"}, {\"$schema\": \"https://aitp.dev/v1/requests.schema.json\"}]},{\"id\": \"hub.near.ai/travel-agent/0.1.0\", \"capabilities\": [{\"$schema\": \"https://aitp.dev/v1/payments.schema.json\"}]}]"
  }
}
```

--------------------------------

### JavaScript Functions for AITP-03 Data Request Message Generation

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-03-data-request/implementation-guide.md

These JavaScript examples illustrate how to programmatically construct the `request_data` message, which an agent sends to a client UI to solicit structured input. It covers both inline field definition and referencing an external JSON form schema.

```javascript
// Example JavaScript for generating a request_data message
function createDataRequest(options) {
  return {
    "$schema": "https://aitp.dev/capabilities/aitp-03-data-request/v1.0.0/schema.json",
    "request_data": {
      "id": generateUniqueId(), // Use UUID or similar
      "title": options.title || "",
      "description": options.description || "",
      "fillButtonLabel": options.buttonLabel || "Fill out form",
      "form": {
        "fields": options.fields.map(field => ({
          "id": field.id,
          "label": field.label,
          "description": field.description || "",
          "default_value": field.defaultValue || "",
          "type": field.type || "text",
          "options": field.options || [],
          "required": field.required || false,
          "autocomplete": field.autocomplete || ""
        }))
      }
    }
  };
}
```

```javascript
// Alternative version using an external JSON definition
function createExternalDataRequest(options) {
  return {
    "$schema": "https://aitp.dev/capabilities/aitp-03-data-request/v1.0.0/schema.json",
    "request_data": {
      "id": generateUniqueId(),
      "title": options.title || "",
      "description": options.description || "",
      "fillButtonLabel": options.buttonLabel || "Fill out form",
      "form": {
        "json_url": options.formUrl
      }
    }
  };
}
```

--------------------------------

### Example AITP-01 Payment Response JSON Schema

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-01-payments/aitp-01-payments.md

A JSON example illustrating a payment response within the AITP-01 protocol. It contains the quote ID, chosen payment method details (type, token, channel ID, amount, currency), payer ID, timestamp, and payer signature, confirming the transaction.

```json
{
  "$schema": "https://aitp.dev/capabilities/aitp-01-payments/v0.1.0/schema.json",
  "payment": {
    "quote_id": "q_123456789",
    "payment_method": {
      "type": "near_payment_channel",
      "token": "usdc.near",
      "channel_id": "ch_987654321",
      "amount": "99.99",
      "currency": "USD"
    },
    "payer_id": "user.near",
    "timestamp": "2025-02-25T08:32:15Z",
    "payer_signature": "ed25519:..."
  }
}
```

--------------------------------

### Agent Confirmation of User Preferences

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-03-data-request/sample-flows.md

An example of an agent's conversational response confirming the user's submitted preferences. This plain text snippet reiterates the collected data points and explains the impact on personalized recommendations, showcasing a typical agent-user interaction.

```text
Agent: Thanks for sharing your preferences! I've saved them and will use them to customize your experience:

- Your favorite color is Teal
- You prefer Medium-sized items
- Your preferred price range is $50-$100
- You've opted in to email notifications

You'll now see more personalized recommendations based on these preferences.
```

--------------------------------

### Example: Payment Confirmation JSON Structure

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-01-payments/schema-reference.md

Illustrates the JSON structure for a payment confirmation message sent by the merchant. This example includes the schema reference, quote and payment IDs, result, timestamp, an optional human-readable message, and additional details about the transaction.

```json
{
  "$schema": "https://aitp.dev/capabilities/aitp-01-payments/v1.0.0/schema.json",
  "payment_confirmation": {
    "quote_id": "q_123456789",
    "payment_id": "pay_987654321",
    "result": "success",
    "timestamp": "2025-02-25T08:33:15Z",
    "message": "Your premium subscription has been activated!",
    "details": [
      {
        "label": "Order Number",
        "value": "ORD-12345",
        "url": "https://example.com/orders/12345"
      },
      {
        "label": "Subscription Period",
        "value": "February 25, 2025 - February 25, 2026"
      }
    ],
    "merchant_signature": "ed25519:..."
  }
}
```

--------------------------------

### Example: Simple Radio Selection Request

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-02-decisions/aitp-02-decisions.md

A practical example of a `request_decision` message for a single-choice radio selection. It prompts the user to select a favorite number from a predefined list of options.

```json
{
  "$schema": "https://aitp.dev/capabilities/aitp-02-decisions/v1.0.0/schema.json",
  "request_decision": {
    "id": "7c42b9d6-107d-4f5f-8f23-f9014c6efdae",
    "description": "Select your favorite number:",
    "options": [
      { "id": "0", "name": "0" },
      { "id": "7", "name": "7" },
      { "id": "100", "name": "100" }
    ]
  }
}
```

--------------------------------

### Example AITP-01 Quote Message

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-01-payments/schema-reference.md

A JSON example demonstrating the structure of a payment quote message. This message is sent by a merchant or service to initiate a payment request, detailing payment options and recipient information.

```json
{
  "$schema": "https://aitp.dev/capabilities/aitp-01-payments/v1.0.0/schema.json",
  "quote": {
    "quote_id": "q_123456789",
    "merchant_id": "store.near",
    "description": "Premium Subscription - Annual Plan",
    "expiration": "2025-03-01T12:00:00Z",
    "next_recipient": "service-agent.near",
    "payment_options": [
      {
        "amount": "99.99",
        "currency": "USD",
        "payment_methods": [
          {
            "type": "near_payment_channel",
            "token": "usdc.near",
            "recipient": "store.near"
          }
        ]
      }
    ],
    "revenue_share": {
      "affiliate_share_bps": 300,
      "affiliates": []
    },
    "merchant_signature": "ed25519:..."
  }
}
```

--------------------------------

### Example `data` Message for Responding to a Data Request

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-03-data-request/aitp-03-data-request.md

Illustrates the structure of a `data` message used to respond to a `request_data` message. It includes the `request_data_id` to link back to the original request and an array of `fields` containing the collected `id`, `label`, and `value` for each field.

```json
{
  "$schema": "https://aitp.dev/capabilities/aitp-03-data-request/v1.0.0/schema.json",
  "data": {
    "request_data_id": "id-from-the-request",
    "fields": [
      {
        "id": "field-id",
        "label": "Field label",
        "value": "User-provided value"
      }
    ]
  }
}
```

--------------------------------

### Example AITP-01 Payment Message

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-01-payments/schema-reference.md

A JSON example demonstrating the structure of a payment message. This message is sent by the payer to authorize payment for a previously issued quote, including details of the payment method and payer identification.

```json
{
  "$schema": "https://aitp.dev/capabilities/aitp-01-payments/v1.0.0/schema.json",
  "payment": {
    "quote_id": "q_123456789",
    "payment_method": {
      "type": "near_payment_channel",
      "token": "usdc.near",
      "channel_id": "ch_987654321",
      "amount": "99.99",
      "currency": "USD"
    },
    "payer_id": "user.near",
    "timestamp": "2025-02-25T08:32:15Z",
    "payer_signature": "ed25519:..."
  }
}
```

--------------------------------

### Create an AITP Message JSON Request

Source: https://github.com/nearai/aitp/blob/main/website/docs/examples.md

This JSON payload illustrates how to create and send a message within an existing AITP thread. It specifies the target thread ID, the role of the sender, actor metadata, and the message content, which includes a structured request for a decision with product options.

```json
{
  "thread_id": "thread_travel-agent-1",
  "role": "assistant",
  "metadata": {
    "actor": "hub.near.ai/travel-agent/0.1.0"
  },
  "content": [
    "{\"$schema\": \"https://aitp.dev/v1/requests.schema.json\", \"request_decision\": {\"type\": \"product\", \"options\": [{\"id\": 1, \"image_url\": \"https://...\", \"name\": \"Red Socks\", \"price\": {\"usd\": 10.5 },\"url\": \"https://amazon.com/...\"}, {\"id\": 2,\"image_url\": \"https://...\",\"name\": \"Blue Socks\",\"price\": {\"usd\": 9 },\"url\": \"https://amazon.com/...\"}]}}"      ]
}
```

--------------------------------

### Example: Top-Up Request JSON Structure

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-01-payments/schema-reference.md

Presents the JSON format for a merchant's top-up request, used to ask for additional funds for an existing payment channel. It includes the channel ID, suggested amount, currency, reason for the request, merchant ID, and timestamp.

```json
{
  "$schema": "https://aitp.dev/capabilities/aitp-01-payments/v1.0.0/schema.json",
  "top_up_request": {
    "channel_id": "ch_987654321",
    "amount": "50.00",
    "currency": "USD",
    "reason": "Additional service usage beyond initial payment",
    "merchant_id": "store.near",
    "timestamp": "2025-02-26T10:15:30Z",
    "merchant_signature": "ed25519:..."
  }
}
```

--------------------------------

### Example: Top-Up Response JSON Structure

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-01-payments/schema-reference.md

Shows the JSON structure for a top-up response, sent by the payer to confirm additional funds have been added to a payment channel. It details the channel ID, amount, currency, new balance, payer ID, timestamp, and payer signature.

```json
{
  "$schema": "https://aitp.dev/capabilities/aitp-01-payments/v1.0.0/schema.json",
  "top_up_response": {
    "channel_id": "ch_987654321",
    "amount": "50.00",
    "currency": "USD",
    "new_balance": "75.50",
    "payer_id": "user.near",
    "timestamp": "2025-02-26T10:20:45Z",
    "payer_signature": "ed25519:..."
  }
}
```

--------------------------------

### Example AITP Wrapped Quote JSON Structure

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-01-payments/aitp-01-payments.md

Demonstrates the JSON structure of a wrapped quote in the AITP-01 payments protocol, including original quote details, payment options, revenue share, and how multiple wrappers (affiliates) are added with their respective roles and signatures. This structure facilitates the distribution of affiliate fees.

```json
{
  "$schema": "https://aitp.dev/capabilities/aitp-01-payments/v0.1.0/schema.json",
  "wrapped_quote": {
    "original_quote": {
      "quote_id": "q_123456789",
      "merchant_id": "store.near",
      "description": "Premium Subscription - Annual Plan",
      "expiration": "2025-03-01T12:00:00Z",
      "next_recipient": "service-agent.near",
      "payment_options": [
        {
          "amount": "99.99",
          "currency": "USD",
          "payment_methods": [
            {
              "type": "near_payment_channel",
              "token": "usdc.near",
              "recipient": "store.near"
            }
          ]
        }
      ],
      "revenue_share": {
        "affiliate_share_bps": 300,
        "affiliates": []
      },
      "merchant_signature": "ed25519:..."
    },
    "wrappers": [
      {
        "affiliate_id": "service-agent.near",
        "role": "service",
        "added_affiliates": [],
        "next_recipient": "assistant.near",
        "timestamp": "2025-02-25T08:29:15Z",
        "signature": "ed25519:..."
      },
      {
        "affiliate_id": "assistant.near",
        "role": "personal_assistant",
        "added_affiliates": [
          {
            "id": "discovery.near",
            "role": "discovery",
            "weight": 1
          }
        ],
        "next_recipient": "user-interface.near",
        "timestamp": "2025-02-25T08:30:15Z",
        "signature": "ed25519:..."
      }
    ]
  }
}
```

--------------------------------

### Example `request_data` Message with Inline Form Definition

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-03-data-request/aitp-03-data-request.md

Demonstrates a `request_data` message structure where the form fields are defined directly within the message. It includes common properties like `id`, `title`, `description`, `fillButtonLabel`, and an array of `fields` with various types and options.

```json
{
  "$schema": "https://aitp.dev/capabilities/aitp-03-data-request/v1.0.0/schema.json",
  "request_data": {
    "id": "unique-form-id",
    "title": "Form title",
    "description": "Description of what information is needed",
    "fillButtonLabel": "Custom button text",
    "form": {
      "fields": [
        {
          "id": "field-id",
          "label": "Field label",
          "description": "Help text",
          "default_value": "Default value",
          "type": "text|number|email|textarea|select|combobox|tel",
          "options": ["Option 1", "Option 2"],
          "required": true,
          "autocomplete": "autocomplete hint"
        }
      ]
    }
  }
}
```

--------------------------------

### Complete AITP Thread Example

Source: https://github.com/nearai/aitp/blob/main/website/docs/threads.md

This JSON snippet demonstrates a full AITP thread, detailing the interaction between a user agent and a travel agent. It includes actor capability declarations, initial user requests, and structured decision-making using AITP capabilities for presenting and selecting flight options.

```json
{
  "id": "thread_abc123",
  "metadata": {
    "parent_id": null,
    "actors": [
      {
        "id": "user-agent.near",
        "capabilities": [
          {"schema": "https://aitp.dev/capabilities/aitp-01-payments/v1.0.0/schema.json"},
          {"schema": "https://aitp.dev/capabilities/aitp-02-decisions/v1.0.0/schema.json"}
        ]
      },
      {
        "id": "travel-agent.near",
        "capabilities": [
          {"schema": "https://aitp.dev/capabilities/aitp-01-payments/v1.0.0/schema.json"},
          {"schema": "https://aitp.dev/capabilities/aitp-03-data-request/v1.0.0/schema.json"}
        ]
      }
    ]
  },
  "messages": [
    {
      "created_at": 1708950000,
      "thread_id": "thread_abc123",
      "content": ["I need to book a flight to Miami next month"],
      "role": "user",
      "metadata": {
        "actor": "user-agent.near"
      }
    },
    {
      "created_at": 1708950060,
      "thread_id": "thread_abc123",
      "content": ["{\"$schema\": \"https://aitp.dev/capabilities/aitp-02-decisions/v1.0.0/schema.json\", \"request_decision\": {\"id\": \"flight_options\", \"type\": \"radio\", \"options\": [{\"id\": \"f1\", \"name\": \"Economy: $299\"}, {\"id\": \"f2\", \"name\": \"Business: $799\"}]}}"],
      "role": "assistant",
      "metadata": {
        "actor": "travel-agent.near"
      }
    },
    {
      "created_at": 1708950120,
      "thread_id": "thread_abc123",
      "content": ["{\"$schema\": \"https://aitp.dev/capabilities/aitp-02-decisions/v1.0.0/schema.json\", \"decision\": {\"request_decision_id\": \"flight_options\", \"options\": [{\"id\": \"f2\"}]}}"],
      "role": "user",
      "metadata": {
        "actor": "user-agent.near"
      }
    }
  ]
}
```

--------------------------------

### Handle AITP-02 decision Response (JavaScript)

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-02-decisions/implementation-guide.md

Demonstrates a JavaScript function for processing an incoming `decision` message from a user or another agent. The function identifies the original request, extracts selected options, and provides logic for handling single selections (radio, confirmation), multiple selections (checkbox), and product selections with quantities.

```javascript
// Example JavaScript for handling a decision response
function handleDecision(decision) {
  // Find the original request
  const requestId = decision.decision.request_decision_id;
  const originalRequest = findRequestById(requestId);
  
  // Process selected options
  const selectedOptions = decision.decision.options;
  
  // For a single selection
  if (originalRequest.request_decision.type === "radio" ||
      originalRequest.request_decision.type === "confirmation") {
    const selectedOption = selectedOptions[0];
    // Take action based on selection
  }
  
  // For multiple selections
  if (originalRequest.request_decision.type === "checkbox") {
    // Process each selected option
    selectedOptions.forEach(option => {
      // Take action based on each selection
    });
  }
  
  // For product selection
  if (originalRequest.request_decision.type === "products") {
    selectedOptions.forEach(product => {
      const quantity = product.quantity || 1;
      // Process product selection with quantity
    });
  }
}
```

--------------------------------

### Generate AITP-02 request_decision Message (JavaScript)

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-02-decisions/implementation-guide.md

Provides a JavaScript function to construct a `request_decision` message, which is used by an agent to present choices to a user. The function includes parameters for title, description, decision type (e.g., radio), and a list of options, ensuring the message conforms to the AITP-02 Decisions schema.

```javascript
// Example JavaScript for generating a request_decision message
function createRequestDecision(options) {
  return {
    "$schema": "https://aitp.dev/capabilities/aitp-02-decisions/v1.0.0/schema.json",
    "request_decision": {
      "id": generateUniqueId(), // Use UUID or similar
      "title": options.title || "",
      "description": options.description || "",
      "type": options.type || "radio",
      "options": options.items.map(item => ({
        "id": item.id,
        "name": item.name,
        // Add other properties based on item type
      }))
    }
  };
}
```

--------------------------------

### User Initiates Cloud Server Configuration

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-02-decisions/sample-flows.md

A user's initial request to an agent to begin the process of setting up a new cloud server for an application.

```text
User: I want to set up a new cloud server for my application.
```

--------------------------------

### Render Checkbox Selection Decision UI in React

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-02-decisions/implementation-guide.md

This React component provides an example for rendering a multi-choice decision UI using checkboxes. It handles multiple selections, constructs the decision payload with all chosen options, and passes it to the `onSubmit` handler according to the AITP schema for decision requests.

```jsx
// React example for rendering checkbox selection
function CheckboxDecision({ request, onSubmit }) {
  const [selected, setSelected] = useState({});
  
  const toggleOption = (id) => {
    setSelected(prev => ({
      ...prev,
      [id]: !prev[id]
    }));
  };
  
  const handleSubmit = () => {
    const selectedOptions = Object.entries(selected)
      .filter(([_, isSelected]) => isSelected)
      .map(([id]) => {
        const option = request.request_decision.options.find(o => o.id === id);
        return { "id": id, "name": option.name };
      });
    
    if (selectedOptions.length > 0) {
      onSubmit({
        "$schema": "https://aitp.dev/capabilities/aitp-02-decisions/v1.0.0/schema.json",
        "decision": {
          "request_decision_id": request.request_decision.id,
          "options": selectedOptions
        }
      });
    }
  };
  
  return (
    <div className="decision-container">
      <h3>{request.request_decision.title}</h3>
      <p>{request.request_decision.description}</p>
      
      <div className="options">
        {request.request_decision.options.map(option => (
          <div key={option.id} className="checkbox-option">
            <input
              type="checkbox"
              id={option.id}
              checked={selected[option.id] || false}
              onChange={() => toggleOption(option.id)}
            />
            <label htmlFor={option.id}>
              {option.name}
              {option.description && <p className="description">{option.description}</p>}
            </label>
          </div>
        ))}
      </div>
      
      <button onClick={handleSubmit} disabled={Object.values(selected).every(v => !v)}>
        Submit
      </button>
    </div>
  );
}
```

--------------------------------

### User Initiates Product Recommendation Request

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-02-decisions/sample-flows.md

A user's initial query to an agent, expressing a need for product recommendations with specific criteria.

```text
User: I'm looking for noise-cancelling headphones under $300.
```

--------------------------------

### Agent Confirms Product Selection and Offers Next Steps

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-02-decisions/sample-flows.md

The agent's natural language response confirming the user's product choice and prompting for further action, such as proceeding with purchase or exploring more options.

```text
Agent: Great choice! You've selected the JBL Tour One M2 headphones for $199.50. 
These offer adaptive noise cancellation with up to 30 hours of battery life.

Would you like to proceed with the purchase or would you like to see more options?
```

--------------------------------

### User Requests Recommendations (Dialogue)

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-02-decisions/sample-flows.md

A plain text dialogue snippet showing a user initiating a request for personalized recommendations, setting the stage for preference collection.

```text
User: I'm looking for a new fiction book to read. Can you recommend something?
```

--------------------------------

### Agent Confirms Action (Dialogue)

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-02-decisions/sample-flows.md

A plain text dialogue snippet where the agent verbally confirms the user's selections and outlines the next steps, such as server creation and availability.

```text
Agent: Great! I'm creating your web server with the Standard tier and additional backup and monitoring features. The total monthly cost will be $65. Your server will be available in approximately 5-10 minutes.
```

--------------------------------

### Agent Requests Product Decision for E-commerce

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-02-decisions/sample-flows.md

The agent's structured JSON request to the AITP-02 Decisions capability, presenting a list of product options (headphones) based on user criteria, including detailed product information, pricing, and images.

```json
{
  "$schema": "https://aitp.dev/capabilities/aitp-02-decisions/v1.0.0/schema.json",
  "request_decision": {
    "id": "bd9b613c-6fa5-4797-ba91-547f0903da9f",
    "title": "Recommended Headphones",
    "description": "Based on your budget and requirements, here are some noise-cancelling headphones under $300:",
    "type": "products",
    "options": [
      {
        "id": "product_1",
        "name": "JBL Tour One M2",
        "description": "Adaptive noise cancellation with up to 30 hours of battery life",
        "five_star_rating": 4.2,
        "reviews_count": 132,
        "quote": {
          "type": "Quote",
          "payee_id": "jbl-store",
          "quote_id": "jbl-tour-one-m2",
          "payment_plans": [
            {
              "amount": 199.5,
              "currency": "USD",
              "plan_id": "one-time-standard",
              "plan_type": "one-time"
            }
          ],
          "valid_until": "2025-03-01T00:00:00Z"
        },
        "image_url": "https://example.com/jbl-tour-one-m2.jpg",
        "url": "https://example.com/jbl-tour-one-m2"
      },
      {
        "id": "product_2",
        "name": "Soundcore by Anker Space One",
        "description": "Budget-friendly with adaptive noise cancellation and 40-hour playtime",
        "five_star_rating": 3.5,
        "reviews_count": 256,
        "quote": {
          "type": "Quote",
          "payee_id": "anker-store",
          "quote_id": "soundcore-space-one",
          "payment_plans": [
            {
              "amount": 79.99,
              "currency": "USD",
              "plan_id": "one-time-standard",
              "plan_type": "one-time"
            }
          ],
          "valid_until": "2025-03-01T00:00:00Z"
        },
        "image_url": "https://example.com/soundcore-space-one.jpg",
        "url": "https://example.com/soundcore-space-one",
        "variants": [
          {
            "id": "product_2_black",
            "name": "Soundcore by Anker Space One - Jet Black",
            "short_variant_name": "Jet Black",
            "five_star_rating": 3.75,
            "quote": {
              "type": "Quote",
              "payee_id": "anker-store",
              "quote_id": "soundcore-space-one-black",
              "payment_plans": [
                {
                  "amount": 89.99,
                  "currency": "USD",
                  "plan_id": "one-time-standard",
                  "plan_type": "one-time"
                }
              ],
              "valid_until": "2025-03-01T00:00:00Z"
            },
            "image_url": "https://example.com/soundcore-space-one-black.jpg",
            "url": "https://example.com/soundcore-space-one-black"
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### User Selects Server Type (AITP Decision)

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-02-decisions/sample-flows.md

Demonstrates an AITP 'decision' payload where the user selects a server type from predefined options, indicating their choice to the agent.

```json
{
  "$schema": "https://aitp.dev/capabilities/aitp-02-decisions/v1.0.0/schema.json",
  "decision": {
    "request_decision_id": "server-type-selection",
    "options": [
      {
        "id": "web-server",
        "name": "Web Server"
      }
    ]
  }
}
```

--------------------------------

### Agent Presents Book Recommendations (AITP JSON)

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-02-decisions/sample-flows.md

JSON payload for an agent's 'request_decision' to display book recommendations. It uses the 'products' type, providing rich metadata like ratings, reviews, images, and URLs for each book.

```json
{
  "$schema": "https://aitp.dev/capabilities/aitp-02-decisions/v1.0.0/schema.json",
  "request_decision": {
    "id": "book-recommendations",
    "title": "Recommended Books",
    "description": "Based on your preferences for science fiction and fantasy standalone novels, here are some recommendations:",
    "type": "products",
    "options": [
      {
        "id": "book1",
        "name": "The Priory of the Orange Tree",
        "description": "An epic fantasy standalone about a world on the brink of war with dragons--and the women who must lead the fight to save it.",
        "five_star_rating": 4.1,
        "reviews_count": 1526,
        "image_url": "https://example.com/book1.jpg",
        "url": "https://example.com/book/priory"
      },
      {
        "id": "book2",
        "name": "Project Hail Mary",
        "description": "A lone astronaut must save the earth from disaster in this incredible new science-based thriller from the #1 New York Times bestselling author of The Martian.",
        "five_star_rating": 4.7,
        "reviews_count": 2341,
        "image_url": "https://example.com/book2.jpg",
        "url": "https://example.com/book/hail-mary"
      },
      {
        "id": "book3",
        "name": "The Starless Sea",
        "description": "A timeless love story set in a secret underground world—a place of pirates, painters, lovers, liars, and ships that sail upon a starless sea.",
        "five_star_rating": 4.0,
        "reviews_count": 1872,
        "image_url": "https://example.com/book3.jpg",
        "url": "https://example.com/book/starless-sea"
      }
    ]
  }
}
```

--------------------------------

### Product Quote Object Structure JSON Example

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-02-decisions/aitp-02-decisions.md

Illustrates the JSON structure for a `quote` object, typically nested within product-specific options. It specifies payment details like `quote_id`, `payee_id`, `payment_plans` (with amount, currency, type), and `valid_until`.

```json
"quote": {
  "type": "Quote",
  "quote_id": "unique-quote-id",
  "payee_id": "merchant-id",
  "payment_plans": [
    {
      "plan_id": "plan-id",
      "plan_type": "one-time",
      "amount": 199.99,
      "currency": "USD"
    }
  ],
  "valid_until": "2050-01-01T00:00:00Z"
}
```

--------------------------------

### Example `request_data` Message Referencing External Form JSON

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-03-data-request/aitp-03-data-request.md

Shows an alternative `request_data` message where the form definition is referenced via an external `json_url` instead of being embedded directly. This allows for dynamic or pre-defined form structures.

```json
{
  "$schema": "https://aitp.dev/capabilities/aitp-03-data-request/v1.0.0/schema.json",
  "request_data": {
    "id": "unique-form-id",
    "title": "Form title",
    "description": "Description of what information is needed",
    "fillButtonLabel": "Custom button text",
    "form": {
      "json_url": "https://example.com/form-definition.json"
    }
  }
}
```

--------------------------------

### User Initiates Preference Personalization

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-03-data-request/sample-flows.md

This text snippet captures a user's conversational request to set their preferences for product recommendations, initiating a new interaction flow.

```text
User: I'd like to set my preferences for product recommendations.
```

--------------------------------

### Decision Response Message JSON Schema Example

Source: https://github.com/nearai/aitp/blob/main/website/docs/capabilities/aitp-02-decisions/aitp-02-decisions.md

Defines the JSON structure for a `decision` message, sent by a client in response to a `request_decision`. It includes the `request_decision_id` to link to the original request and an array of `options` representing the selected choices, optionally with `quantity` for product selections.

```json
{
  "$schema": "https://aitp.dev/capabilities/aitp-02-decisions/v1.0.0/schema.json",
  "decision": {
    "request_decision_id": "id-from-the-request",
    "options": [
      {
        "id": "selected-option-id",
        "name": "Optional name of selected option",
        "quantity": 1 // Optional, for product selections
      },
      // More selected options if multiple selection is allowed
    ]
  }
}
```