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). 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/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": [ {