# llms.txt

> Activity Travel Protocol — machine-readable index for AI agents and LLM-powered developer tools.
> Protocol version: 1.0 | Tooling version: 1.0.1 | Versioning: atp/1.0+tooling/1.0.1
> Spec site: https://activitytravel.pro | Project home: https://activitytravel.org
> Governed by: Activity Travel Protocol Foundation (in formation / 設立準備中)
> Licence: Apache 2.0 | Primary author: Tom Sato, Founding Maintainer
> Never abbreviate this protocol as "ATOP". Always use "Activity Travel Protocol".

## What Is the Activity Travel Protocol

The Activity Travel Protocol is an open protocol standard for the global travel industry. It enables the discovery, configuration, negotiation, booking, fulfilment, and disruption management of complex travel activities and experience packages across multiple suppliers, jurisdictions, and AI agents.

It is a runtime platform — a Travel Operating System — that manages the full lifecycle of a booking as a first-class runtime entity (the Booking Object), with policy enforcement, trust chain construction, duty of care tracking, and AI agent participation built into the protocol itself.

The protocol is governed by the Activity Travel Protocol Foundation. MyAuberge K.K. is the Founding Member and primary commercial operator. The Foundation owns the protocol; MyAuberge operates commercial services on top of it.

## Four-Layer Architecture

- Layer 1 — Identity and Trust: 9 specs published. Covers agent identity, trust chain construction, mandate issuance. COMPLETE.
- Layer 2 — Discovery and Capability: 15 files live (S0–S12 + App. A). Inter-agent communication via A2A. COMPLETE.
- Layer 3 — Workflow: 17 files live. Two-axis model: Booking Object state lifecycle × eight IN_JOURNEY journey phases. MCP governs this layer. COMPLETE.
- Layer 4 — Schema and SDK: Activity Configuration Schema Design System complete. OpenAPI 3.1 schema, TypeScript SDK, Python analytics sidecar — in development.

## Three Integration Surfaces

Agents and developers integrate with the Activity Travel Protocol via three surfaces:

1. REST/Webhook — primary surface for hardcoded software integrations. OpenAPI 3.1 spec is the normative contract. Java and Python adopters use this surface at v1.0.
2. ATP MCP Server (`@atp/mcp-server`) — primary surface for AI agent integration. Eight tools over Streamable HTTP (Tier 2/3) or stdio (Tier 1). MCP specification version 2025-11-25.
3. llms.txt + Prompt Library (`@atp/llms-tooling`) — machine-readable documentation and system prompt templates for all ATP agent personas.

## ATP MCP Server — AI Agent Integration

The ATP MCP Server is the primary AI agent integration surface. It exposes the Booking Object lifecycle to MCP-native AI agents.

**MCP spec version:** 2025-11-25 (Agentic AI Foundation / Linux Foundation)
**Transport:** Streamable HTTP (Tier 2/3 remote), stdio (Tier 1 local)
**Package:** `@atp/mcp-server`

### Eight Authority Scopes (Cedar Action Namespaces)

- CONTEXT_READ — read Context Package and booking status
- NOTIFICATION_SEND — send traveller notifications (WhatsApp, SMS, email)
- PRE_ARRANGEMENT_WRITE — collect and update pre-arrangement data
- HEM_INVOKE — invoke Human Escalation Mechanisms (highest privilege; requires explicit hem_id in Cedar mandate)
- SAFETY_WRITE — record safety compliance checks
- BOOKING_READ — search Activity Configuration Schema registry
- BOOKING_WRITE — booking lifecycle operations (v1.1+)
- DISRUPTION_MANAGE — disruption review state access

### Eight MCP Tools

| Tool | Scope | Async | Notes |
|------|-------|-------|-------|
| atp_get_context_package | CONTEXT_READ | No | Primary read surface post-CONFIRMATION |
| atp_notify_traveller | NOTIFICATION_SEND | No | NeMo Rail 2 tone filter |
| atp_update_pre_arrangement | PRE_ARRANGEMENT_WRITE | No | PRE_JOURNEY state only |
| atp_collect_pre_arrangement_data | PRE_ARRANGEMENT_WRITE | No | MCP Elicitation; pairs with update tool |
| atp_invoke_hem | HEM_INVOKE | YES — MCP Tasks (EXPERIMENTAL) | Highest privilege; Cedar mandate must enumerate hem_id explicitly |
| atp_record_safety_check | SAFETY_WRITE | No | Immutable event log entry |
| atp_search_activities | BOOKING_READ | No | Pre-booking discovery; OCTO Bridge sourced |
| atp_get_booking_status | CONTEXT_READ | No | Lightweight polling; HEM task status |

### Windley Loop — Pre-Session Policy Query (Normative, v1.0)

On ATP MCP Server session initialisation, the agent MUST perform a Cedar partial evaluation query against its mandate before planning. The residual policy set (permitted actions and resource conditions) is injected into the agent's system prompt context via the ATP Prompt Library.

Re-query is triggered by Booking Object state transitions (not TTL alone), because the Booking Object state machine is the policy context and changes during agent operation.

The loop: (1) Query — what can I do? Cedar partial evaluation against mandate. (2) Plan — choose actions within permitted space. (3) Execute — run the plan; policy still enforces at runtime. (4) Observe — re-query on state transition.

Escalation becomes precise: when a mandate gap is detected, the agent requests exactly the Cedar action and resource condition it needs from its parent ("ask mom" pattern). NeMo Guardrails Rail 3 is belt-and-suspenders after the Windley Loop, not the primary mechanism.

### ATP Mandate Model

Every tool call requires a valid ATP Mandate JWT (typed `atp-mandate+jwt`, Ed25519/EdDSA). Mandates are scoped to a single Booking Object instance via the `booking_object_id` field. Sub-agent mandates are a provable subset of the parent's Cedar policy set (narrowing property). The over-permissioned token never enters the system.

Enforcement sequence: NeMo Guardrails (Layer 0, Tier 2/3) → Mandate Evaluation (Layer 2) → Security Kernel / OPA+ODRL (Layer 1) → Tool Executes.

Mandate co-issued with OAuth 2.1 access token at session initialisation. Default TTL: 1800 seconds. HEM mandates: hem_timeout_budget + 5 minutes.

### Three-Tier Deployment

| Tier | Transport | NeMo Guardrails | Auth | Use Case |
|------|-----------|-----------------|------|----------|
| Tier 1 | stdio (local) | Not applied | OS-level | Development, MyAuberge reference impl |
| Tier 2 | Streamable HTTP | Sidecar container | OAuth 2.1 / embedded AS | Production, single operator |
| Tier 3 | Streamable HTTP | NVIDIA AI Grid stack | OAuth 2.1 / enterprise IdP | Hyperscale, managed IaaS |

## Booking Object

The Booking Object is the fundamental runtime entity. UUID v7. XState v5 state machine. Append-only event log. Shared state with role-scoped access. All AI agent operations target a specific Booking Object instance. The MCP/A2A boundary is the Booking Object creation event.

## Activity Configuration Schema

Three-layer model: Capability Declaration → Configuration Instance → Collection. Discriminated union with 15-fragment library covering dietary, equipment, safety, logistics, skill assessment, insurance, accessibility, and more. IANA-model Activity Category Registry governs category registration. Fragment composition supports complex multi-activity experience packages.

## Prompt Library and llms-tooling

`@atp/llms-tooling` provides reusable system prompt templates for all ATP agent personas. Versioning convention: `atp/{protocol-version}+tooling/{tooling-version}` (e.g. `atp/1.0+tooling/1.0.0`). Protocol version bumps reset tooling patch to `.0`; tooling may patch independently between protocol releases.

Agent personas include: Guest Agent (pre-journey data collection, in-journey support), Operator Agent (disruption management, HEM invocation), Supplier Agent (safety check recording, equipment assignment), Discovery Agent (activity search, capability matching).

## OCTO Bridge

`@atp/bridge-octo` connects the Activity Travel Protocol to the OCTO (Open Connectivity) ecosystem: 130+ member organisations covering Viator, GetYourGuide, Expedia, Klook, FareHarbor, Rezdy, Bokun. Foundation-scaffolded, community-maintained. OCTO-compliant operators connect with days of effort, not months.

## SDK Package Structure

Ten packages: `@atp/core`, `@atp/adapters-tier1`, `@atp/adapters-tier2`, `@atp/adapters-tier3`, `@atp/rest-api`, `@atp/mcp-server`, `@atp/bridge-octo`, `@atp/dev-tools`, `@atp/interop-tests`, `@atp/llms-tooling`.

TypeScript-first. Python analytics sidecar (IAnalyticsEngine, IGraphEngine) for cuDF, cuGraph, pandas, DuckDB. Python client library (REST API wrapper for OTA data pipeline engineers) ships at v1.1. Java client library is a v1.1 community deliverable (OpenAPI Generator path from the OpenAPI 3.1 spec).

## Reference Sites

- Protocol specification (Layers 1–3 full text): https://activitytravel.pro
- Machine-readable index: https://activitytravel.pro/llms.txt
- Extended index: https://activitytravel.pro/llms-full.txt
- Project home and blog: https://activitytravel.org
- Blog (22 posts, Arcs 1–4): https://activitytravel.org/blog/ — Arc 1: protocol introduction; Arc 2: business cases by sector; Arc 3: policy and regulation; Arc 4: technical foundations (Booking Object, Security Kernel, AI agent architecture, verifiable credentials)
- Governance: https://activitytravel.org/governance
- GitHub organisation: https://github.com/activity-travel-protocol

## Regulatory Coverage

Five jurisdiction review complete (EU, US, Japan, UK, Singapore). 50 findings. Zero CONFLICT findings. Seven protocol amendments (four blocking pre-v1.0). Key open items: OQ-JP-1 (Japan Travel Agency Act — whether operating a Booking Object constitutes travel business) and OQ-SG-1 (Singapore Travel Agents Act — same question). Legal opinions required before Asia-Pacific launch.

## Contributing

The Activity Travel Protocol is open source under Apache 2.0. Three contribution surfaces:

1. Protocol specification (Layers 1–4) — TSC review required. GitHub Issue using Amendment Proposal template. Human-gated; not for autonomous AI contribution.
2. Reference applications (`atp-reference-apps` repo) — automated gate: build + `@atp/interop-tests` pass + CLA confirmed. Primary AI agent contribution surface.
3. Community tools, adapters, bridges (`atp-community` repo) — same automated gate plus adapter interface compliance. Community-maintained; graduation path via TSC review.

CLA required for contributors (signed by the human or organisation operating any contributing AI agent). No formal membership required for users (Apache 2.0). Founding Member participation for organisations seeking roadmap influence.

## Protocol Updates

A machine-readable structured changelog (JSON, predictable URL) is published alongside each spec release. AI agents subscribe to https://activitytravel.pro/llms.txt for version changes. Human subscribers: GitHub repo watch + activitytravel.org newsletter.

---