From 5db244444e1acec45f14702774aa3cd0e3fe04f8 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 22 Nov 2025 15:55:00 -0500 Subject: [PATCH 1/2] Add artifactId to A2A documentation examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix A2A protocol compliance issues in documentation by adding missing artifactId fields and correcting request structure. **Changes:** - Add artifactId to all 11 A2A artifact examples across 8 files - Fix skill invocation: use 'parameters' not 'input' (3 instances) - Fix message structure: wrap in message.parts[] envelope (5 instances) - Fix webhook config: move to configuration.pushNotificationConfig (2 instances) **Why this matters:** - artifactId is part of A2A protocol for artifact identification/versioning - Correct field names ensure examples work when developers copy them - Proper message structure matches A2A specification **Files modified:** - docs/media-buy/advanced-topics/orchestrator-design.mdx - docs/media-buy/task-reference/create_media_buy.mdx - docs/media-buy/task-reference/provide_performance_feedback.mdx - docs/protocols/a2a-guide.mdx - docs/protocols/envelope-examples.mdx - docs/protocols/getting-started.mdx - docs/protocols/protocol-comparison.mdx - docs/signals/tasks/activate_signal.mdx - docs/signals/tasks/get_signals.mdx Incorporates fixes from PR #231 by @EmmaLouise2018. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../advanced-topics/orchestrator-design.mdx | 4 +- .../task-reference/create_media_buy.mdx | 75 ++++++++++++------- .../provide_performance_feedback.mdx | 3 +- docs/protocols/a2a-guide.mdx | 22 ++++-- docs/protocols/envelope-examples.mdx | 2 + docs/protocols/getting-started.mdx | 1 + docs/protocols/protocol-comparison.mdx | 3 +- docs/signals/tasks/activate_signal.mdx | 1 + docs/signals/tasks/get_signals.mdx | 1 + 9 files changed, 74 insertions(+), 38 deletions(-) diff --git a/docs/media-buy/advanced-topics/orchestrator-design.mdx b/docs/media-buy/advanced-topics/orchestrator-design.mdx index 116990f8d3..0e2ac06952 100644 --- a/docs/media-buy/advanced-topics/orchestrator-design.mdx +++ b/docs/media-buy/advanced-topics/orchestrator-design.mdx @@ -558,7 +558,9 @@ class AdCPOrchestrator: } }] }, - "push_notification_config": webhook_config + "configuration": { + "pushNotificationConfig": webhook_config + } }) # 4. Handle response with unified status handling diff --git a/docs/media-buy/task-reference/create_media_buy.mdx b/docs/media-buy/task-reference/create_media_buy.mdx index d49633ee66..aaf3d5ff13 100644 --- a/docs/media-buy/task-reference/create_media_buy.mdx +++ b/docs/media-buy/task-reference/create_media_buy.mdx @@ -366,6 +366,7 @@ data: {"message": "Validating packages..."} data: {"message": "Checking inventory availability..."} data: {"message": "Creating campaign in ad server..."} data: {"status": {"state": "completed"}, "artifacts": [{ + "artifactId": "artifact-mb-conf-abc123", "name": "media_buy_confirmation", "parts": [ {"kind": "text", "text": "Successfully created $100,000 media buy. Upload creatives by Jan 30."}, @@ -390,7 +391,7 @@ data: {"status": {"state": "completed"}, "artifacts": [{ - **A2A**: Always returns task with updates via: - Server-Sent Events (SSE) for real-time streaming - Webhooks (push notifications) for long-running tasks -- **Payload**: The `input` field in A2A contains the exact same structure as MCP's `arguments` +- **Payload**: The `parameters` field in A2A contains the exact same structure as MCP's `arguments` ## Human-in-the-Loop Examples @@ -466,17 +467,24 @@ A2A can use Server-Sent Events for real-time streaming or webhooks for push noti **Initial Request with SSE:** ```json { - "skill": "create_media_buy", - "input": { - "buyer_ref": "large_campaign_2024", - "packages": [...], - "brand_manifest": { - "name": "ACME Corporation", - "url": "https://acmecorp.com" - }, - "po_number": "PO-2024-LARGE-001", - "start_time": "2024-02-01T00:00:00Z", - "end_time": "2024-06-30T23:59:59Z" + "message": { + "parts": [{ + "kind": "data", + "data": { + "skill": "create_media_buy", + "parameters": { + "buyer_ref": "large_campaign_2024", + "packages": [...], + "brand_manifest": { + "name": "ACME Corporation", + "url": "https://acmecorp.com" + }, + "po_number": "PO-2024-LARGE-001", + "start_time": "2024-02-01T00:00:00Z", + "end_time": "2024-06-30T23:59:59Z" + } + } + }] } } ``` @@ -501,7 +509,7 @@ data: {"message": "Sales team notified. Expected review time: 2-4 hours"} data: {"message": "First approval received from regional manager"} data: {"message": "Second approval received from finance team"} data: {"status": {"state": "completed"}, "artifacts": [{ - "artifactId": "artifact-mb-large-xyz", + "artifactId": "artifact-mb-approval-xyz789", "name": "media_buy_confirmation", "parts": [ {"kind": "text", "text": "Media buy approved and created successfully. $500,000 campaign scheduled Feb 1 - Jun 30. Upload creatives by Jan 30."}, @@ -520,22 +528,31 @@ data: {"status": {"state": "completed"}, "artifacts": [{ **Initial Request with Webhook Configuration:** ```json { - "skill": "create_media_buy", - "input": { - "buyer_ref": "large_campaign_2024", - "packages": [...], - "brand_manifest": { - "name": "ACME Corporation", - "url": "https://acmecorp.com" - }, - "po_number": "PO-2024-LARGE-001", - "start_time": "2024-02-01T00:00:00Z", - "end_time": "2024-06-30T23:59:59Z" + "message": { + "parts": [{ + "kind": "data", + "data": { + "skill": "create_media_buy", + "parameters": { + "buyer_ref": "large_campaign_2024", + "packages": [...], + "brand_manifest": { + "name": "ACME Corporation", + "url": "https://acmecorp.com" + }, + "po_number": "PO-2024-LARGE-001", + "start_time": "2024-02-01T00:00:00Z", + "end_time": "2024-06-30T23:59:59Z" + } + } + }] }, - "pushNotificationConfig": { - "url": "https://buyer.example.com/webhooks/adcp", - "authType": "bearer", - "authToken": "secret-token-xyz" + "configuration": { + "pushNotificationConfig": { + "url": "https://buyer.example.com/webhooks/adcp", + "authType": "bearer", + "authToken": "secret-token-xyz" + } } } ``` @@ -568,7 +585,7 @@ data: {"status": {"state": "completed"}, "artifacts": [{ "contextId": "ctx-conversation-xyz", "status": {"state": "completed"}, "artifacts": [{ - "artifactId": "artifact-mb-webhook-xyz", + "artifactId": "artifact-mb-webhook-def456", "name": "media_buy_confirmation", "parts": [ {"kind": "data", "data": { diff --git a/docs/media-buy/task-reference/provide_performance_feedback.mdx b/docs/media-buy/task-reference/provide_performance_feedback.mdx index bb9d676d5d..f018d84292 100644 --- a/docs/media-buy/task-reference/provide_performance_feedback.mdx +++ b/docs/media-buy/task-reference/provide_performance_feedback.mdx @@ -120,6 +120,7 @@ A2A returns results as artifacts: ```json { "artifacts": [{ + "artifactId": "artifact-perf-feedback-abc789", "name": "performance_feedback_confirmation", "parts": [ { @@ -127,7 +128,7 @@ A2A returns results as artifacts: "text": "Performance feedback received for campaign gam_1234567890. The 35% above-expected conversion rate will be used to optimize future delivery. Next optimization cycle runs tonight at midnight UTC." }, { - "kind": "data", + "kind": "data", "data": { "success": true } diff --git a/docs/protocols/a2a-guide.mdx b/docs/protocols/a2a-guide.mdx index e338b9eb8a..16bdd758ff 100644 --- a/docs/protocols/a2a-guide.mdx +++ b/docs/protocols/a2a-guide.mdx @@ -162,6 +162,7 @@ AdCP responses over A2A **MUST** include at least one `DataPart` (kind: 'data') "taskId": "task-123", // A2A task identifier "contextId": "ctx-456", // Automatic context management "artifacts": [{ // A2A-specific artifact structure + "artifactId": "artifact-product-catalog-abc", "name": "product_catalog", "parts": [ { @@ -193,13 +194,22 @@ AdCP responses over A2A **MUST** include at least one `DataPart` (kind: 'data') AdCP responses use the **last `DataPart` as authoritative** when multiple data parts exist (e.g., from streaming operations): ```javascript -// Extract AdCP data from A2A response -const data = response.artifacts?.[0]?.parts - ?.filter(p => p.kind === 'data') - .slice(-1)[0]?.data; // Last data part is authoritative +// Extract the artifact (currently AdCP returns single artifact per response) +const artifact = response.artifacts?.[0]; + +if (artifact) { + const message = artifact.parts?.find(p => p.kind === 'text')?.text; + const data = artifact.parts?.find(p => p.kind === 'data')?.data; + + return { + artifactId: artifact.artifactId, + message, + data, + status: response.status + }; +} -const message = response.artifacts?.[0]?.parts - ?.find(p => p.kind === 'text')?.text; +return { status: response.status }; ``` **For complete response structure requirements, error handling, and implementation patterns, see [A2A Response Format](/docs/protocols/a2a-response-format).** diff --git a/docs/protocols/envelope-examples.mdx b/docs/protocols/envelope-examples.mdx index 57bcefa99d..514a3f623e 100644 --- a/docs/protocols/envelope-examples.mdx +++ b/docs/protocols/envelope-examples.mdx @@ -105,6 +105,7 @@ MCP sends progress notifications separately: "state": "completed", "artifacts": [ { + "artifactId": "artifact-get-products-abc123", "name": "get_products_result", "content_type": "application/json", "content": "{\"products\": [...]}" @@ -155,6 +156,7 @@ Later, webhook notification: "state": "completed", "artifacts": [ { + "artifactId": "artifact-media-buy-webhook-def456", "name": "create_media_buy_result", "content_type": "application/json", "content": "{\"media_buy_id\": \"mb_789\", ...}" diff --git a/docs/protocols/getting-started.mdx b/docs/protocols/getting-started.mdx index 98c0aa31d1..305d34758d 100644 --- a/docs/protocols/getting-started.mdx +++ b/docs/protocols/getting-started.mdx @@ -109,6 +109,7 @@ Both protocols support all features - they just express them differently: { "contextId": "ctx-123", "artifacts": [{ + "artifactId": "artifact-product-catalog-xyz123", "name": "product_catalog", "parts": [ {"kind": "text", "text": "Found 5 CTV products"}, diff --git a/docs/protocols/protocol-comparison.mdx b/docs/protocols/protocol-comparison.mdx index 21c15ceb23..6889f223c0 100644 --- a/docs/protocols/protocol-comparison.mdx +++ b/docs/protocols/protocol-comparison.mdx @@ -72,10 +72,11 @@ Same status and data, different packaging: "status": "input-required", "contextId": "ctx-123", "artifacts": [{ + "artifactId": "artifact-product-discovery-xyz", "name": "product_discovery", "parts": [ { - "kind": "text", + "kind": "text", "text": "I need your budget and target audience" }, { diff --git a/docs/signals/tasks/activate_signal.mdx b/docs/signals/tasks/activate_signal.mdx index 053c307736..d67c00aabe 100644 --- a/docs/signals/tasks/activate_signal.mdx +++ b/docs/signals/tasks/activate_signal.mdx @@ -264,6 +264,7 @@ data: {"message": "Validating signal access permissions..."} data: {"message": "Configuring deployment on The Trade Desk..."} data: {"message": "Finalizing activation..."} data: {"status": {"state": "completed"}, "artifacts": [{ + "artifactId": "artifact-signal-activation-abc123", "name": "signal_activation_result", "parts": [ {"kind": "text", "text": "Signal successfully activated on The Trade Desk"}, diff --git a/docs/signals/tasks/get_signals.mdx b/docs/signals/tasks/get_signals.mdx index e443680daf..cdc1472aee 100644 --- a/docs/signals/tasks/get_signals.mdx +++ b/docs/signals/tasks/get_signals.mdx @@ -342,6 +342,7 @@ A2A returns results as artifacts with the same data structure: ```json { "artifacts": [{ + "artifactId": "artifact-signal-discovery-def456", "name": "signal_discovery_result", "parts": [ { From 594f09e0cec21def6554e14acdd97a6803fa976a Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 22 Nov 2025 15:58:27 -0500 Subject: [PATCH 2/2] Add changeset for A2A artifactId documentation fixes --- .changeset/a2a-artifact-id-docs.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/a2a-artifact-id-docs.md diff --git a/.changeset/a2a-artifact-id-docs.md b/.changeset/a2a-artifact-id-docs.md new file mode 100644 index 0000000000..8698ef7d7d --- /dev/null +++ b/.changeset/a2a-artifact-id-docs.md @@ -0,0 +1,5 @@ +--- +"adcontextprotocol": patch +--- + +Add artifactId to A2A documentation examples. Fixes A2A protocol compliance issues by adding missing artifactId fields to all artifact examples and correcting request structure (field names, message wrapper, webhook config location).