diff --git a/docs/media-buy/index.md b/docs/media-buy/index.md index 395a324a38..5a9d778318 100644 --- a/docs/media-buy/index.md +++ b/docs/media-buy/index.md @@ -124,6 +124,7 @@ Detailed implementation guidance: - **[Task Reference](./tasks/get_products.md)** - Complete task documentation with examples - **[Design Decisions](design-decisions.md)** - Architectural choices and rationale - **[Testing and Development](testing.md)** - Time simulation and dry run capabilities for faster development +- **[Protocol Test Harness](https://storylab.scope3.com/sales-agents)** - Interactive tool for validating AdCP implementation compliance ## Getting Started diff --git a/docs/media-buy/testing.md b/docs/media-buy/testing.md index f63045f67b..0828b9dd70 100644 --- a/docs/media-buy/testing.md +++ b/docs/media-buy/testing.md @@ -4,6 +4,10 @@ AdCP servers support time simulation and dry run capabilities to enable comprehensive testing of advertising workflows without waiting for real-time events or spending actual budgets. +## Protocol Compliance Testing + +Use the [AdCP Protocol Test Harness](https://storylab.scope3.com/sales-agents) to validate your implementation's compliance with the AdCP specification. This interactive tool allows you to test all AdCP tasks and verify correct behavior across different scenarios. + ## Testing Modes ### Dry Run Mode diff --git a/docs/reference/data-models.md b/docs/reference/data-models.md index d906676fee..617ccac8f9 100644 --- a/docs/reference/data-models.md +++ b/docs/reference/data-models.md @@ -108,22 +108,23 @@ interface Targeting { } ``` -## Response Format +## Protocol Response Format -Standard response structure (MCP). +Protocol-level response wrapper (MCP/A2A). **JSON Schema**: [`/schemas/v1/core/response.json`](/schemas/v1/core/response.json) ```typescript -interface Response { - message: string; // Human-readable summary - context_id?: string; // Session continuity - data?: any; // Operation-specific data - errors?: Error[]; // Non-fatal warnings - clarification_needed?: boolean; +interface ProtocolResponse { + message: string; // Human-readable summary (protocol level) + context_id?: string; // Session continuity (protocol level) + data: any; // AdCP task-specific response data + errors?: Error[]; // Non-fatal warnings (protocol level) } ``` +**Note**: Individual AdCP task schemas contain only the application-level data that goes in the `data` field of the protocol response. + ## Error Standard error structure. diff --git a/static/schemas/v1/core/response.json b/static/schemas/v1/core/response.json index a86a4f153d..cb37b3991b 100644 --- a/static/schemas/v1/core/response.json +++ b/static/schemas/v1/core/response.json @@ -1,8 +1,8 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "/schemas/v1/core/response.json", - "title": "Response", - "description": "Standard response structure (MCP)", + "title": "Protocol Response", + "description": "Protocol-level response wrapper (MCP/A2A) - contains AdCP task data plus protocol fields", "type": "object", "properties": { "message": { @@ -14,7 +14,7 @@ "description": "Session continuity identifier" }, "data": { - "description": "Operation-specific data" + "description": "AdCP task-specific response data (see individual task response schemas)" }, "errors": { "type": "array", @@ -22,10 +22,6 @@ "items": { "$ref": "/schemas/v1/core/error.json" } - }, - "clarification_needed": { - "type": "boolean", - "description": "Whether clarification is needed" } }, "required": ["message"], diff --git a/static/schemas/v1/media-buy/add-creative-assets-response.json b/static/schemas/v1/media-buy/add-creative-assets-response.json index 77ba5fea25..f5be8c0800 100644 --- a/static/schemas/v1/media-buy/add-creative-assets-response.json +++ b/static/schemas/v1/media-buy/add-creative-assets-response.json @@ -5,14 +5,6 @@ "description": "Response payload for add_creative_assets task", "type": "object", "properties": { - "message": { - "type": "string", - "description": "Human-readable status message" - }, - "context_id": { - "type": "string", - "description": "Session continuity identifier" - }, "asset_statuses": { "type": "array", "description": "Array of status information for each uploaded asset", diff --git a/static/schemas/v1/media-buy/create-media-buy-response.json b/static/schemas/v1/media-buy/create-media-buy-response.json index 0212b3a74b..843045e3fb 100644 --- a/static/schemas/v1/media-buy/create-media-buy-response.json +++ b/static/schemas/v1/media-buy/create-media-buy-response.json @@ -5,14 +5,6 @@ "description": "Response payload for create_media_buy task", "type": "object", "properties": { - "message": { - "type": "string", - "description": "Human-readable confirmation message" - }, - "context_id": { - "type": "string", - "description": "Session continuity identifier" - }, "media_buy_id": { "type": "string", "description": "Publisher's unique identifier for the created media buy" diff --git a/static/schemas/v1/media-buy/get-media-buy-delivery-response.json b/static/schemas/v1/media-buy/get-media-buy-delivery-response.json index 0b895e9148..41ec0bb20e 100644 --- a/static/schemas/v1/media-buy/get-media-buy-delivery-response.json +++ b/static/schemas/v1/media-buy/get-media-buy-delivery-response.json @@ -5,14 +5,6 @@ "description": "Response payload for get_media_buy_delivery task", "type": "object", "properties": { - "message": { - "type": "string", - "description": "Human-readable summary of campaign performance" - }, - "context_id": { - "type": "string", - "description": "Session continuity identifier" - }, "reporting_period": { "type": "object", "description": "Date range for the report", diff --git a/static/schemas/v1/media-buy/get-products-response.json b/static/schemas/v1/media-buy/get-products-response.json index 1bc2fdecda..d36457fe24 100644 --- a/static/schemas/v1/media-buy/get-products-response.json +++ b/static/schemas/v1/media-buy/get-products-response.json @@ -5,31 +5,12 @@ "description": "Response payload for get_products task", "type": "object", "properties": { - "message": { - "type": "string", - "description": "Human-readable summary of the response" - }, - "context_id": { - "type": "string", - "description": "Session continuity identifier" - }, "products": { "type": "array", "description": "Array of matching products", "items": { "$ref": "/schemas/v1/core/product.json" } - }, - "clarification_needed": { - "type": "boolean", - "description": "Whether clarification is needed" - }, - "errors": { - "type": "array", - "description": "Non-fatal warnings", - "items": { - "$ref": "/schemas/v1/core/error.json" - } } }, "required": ["products"], diff --git a/static/schemas/v1/media-buy/list-creative-formats-response.json b/static/schemas/v1/media-buy/list-creative-formats-response.json index d67ca7c572..deeac0219b 100644 --- a/static/schemas/v1/media-buy/list-creative-formats-response.json +++ b/static/schemas/v1/media-buy/list-creative-formats-response.json @@ -5,14 +5,6 @@ "description": "Response payload for list_creative_formats task", "type": "object", "properties": { - "message": { - "type": "string", - "description": "Human-readable summary of available formats" - }, - "context_id": { - "type": "string", - "description": "Session continuity identifier" - }, "formats": { "type": "array", "description": "Array of available creative formats", diff --git a/static/schemas/v1/media-buy/update-media-buy-response.json b/static/schemas/v1/media-buy/update-media-buy-response.json index 9ddb6c924d..f75794f1d8 100644 --- a/static/schemas/v1/media-buy/update-media-buy-response.json +++ b/static/schemas/v1/media-buy/update-media-buy-response.json @@ -5,14 +5,6 @@ "description": "Response payload for update_media_buy task", "type": "object", "properties": { - "message": { - "type": "string", - "description": "Human-readable confirmation of changes made" - }, - "context_id": { - "type": "string", - "description": "Session continuity identifier" - }, "media_buy_id": { "type": "string", "description": "Publisher's identifier for the media buy" diff --git a/static/schemas/v1/signals/activate-signal-response.json b/static/schemas/v1/signals/activate-signal-response.json index 247bd614a1..976b27ec72 100644 --- a/static/schemas/v1/signals/activate-signal-response.json +++ b/static/schemas/v1/signals/activate-signal-response.json @@ -5,14 +5,6 @@ "description": "Response payload for activate_signal task", "type": "object", "properties": { - "message": { - "type": "string", - "description": "Human-readable status message" - }, - "context_id": { - "type": "string", - "description": "Session continuity identifier" - }, "task_id": { "type": "string", "description": "Unique identifier for tracking the activation" diff --git a/static/schemas/v1/signals/get-signals-response.json b/static/schemas/v1/signals/get-signals-response.json index a8863be15c..0c2137e243 100644 --- a/static/schemas/v1/signals/get-signals-response.json +++ b/static/schemas/v1/signals/get-signals-response.json @@ -5,14 +5,6 @@ "description": "Response payload for get_signals task", "type": "object", "properties": { - "message": { - "type": "string", - "description": "Human-readable summary of signals found" - }, - "context_id": { - "type": "string", - "description": "Session continuity identifier" - }, "signals": { "type": "array", "description": "Array of matching signals",