Fix A2A payload structure in documentation examples

[EmmaLouise2018]

Problem

A2A (Agent-to-Agent Protocol) documentation examples were inconsistent and confusing developers. Examples showed incorrect payload structures that didn't match the A2A specification.

Issues Fixed

1. Wrong Field Names in Skill Invocation

• Issue: Used "input" instead of "parameters" in skill invocation data
• Fixed: All A2A examples now use "parameters" (3 instances in create_media_buy.mdx)

2. Missing A2A Message Wrapper

• Issue: Examples showed flat structure instead of proper message.parts[] wrapper
• Fixed: Added complete A2A message structure (2 instances)

3. Incorrect Config Location

• Issue: pushNotificationConfig shown inside skill data instead of in configuration object
• Fixed: Moved to proper configuration level (2 instances across 2 files)

4. Missing artifactId in A2A Responses

• Issue: No A2A response examples included required artifactId field
• Fixed: Added artifactId to all 11 A2A response examples across 8 files
• Why: A2A protocol requires artifactId for artifact identification (critical for multi-artifact responses)

Files Modified

Request Structure Fixes:

• docs/media-buy/task-reference/create_media_buy.mdx - Fixed 3 A2A request examples
• docs/media-buy/advanced-topics/orchestrator-design.mdx - Fixed webhook config location

Response Structure Fixes (artifactId added):

• docs/protocols/a2a-guide.mdx - Updated response structure and processing example
• docs/media-buy/task-reference/create_media_buy.mdx - Added to 3 response examples
• docs/signals/tasks/activate_signal.mdx
• docs/signals/tasks/get_signals.mdx
• docs/protocols/protocol-comparison.mdx
• docs/protocols/envelope-examples.mdx - Added to 2 examples
• docs/protocols/getting-started.mdx
• docs/media-buy/task-reference/provide_performance_feedback.mdx

Canonical A2A Structure (Now Consistent)

Request Structure:

{
  "message": {
    "parts": [{
      "kind": "data",
      "data": {
        "skill": "task_name",
        "parameters": { ... }  // Always "parameters", never "input"
      }
    }]
  },
  "configuration": {  // pushNotificationConfig goes here
    "pushNotificationConfig": { ... }
  }
}

Response Structure:

{
  "status": "completed",
  "taskId": "task-123",
  "contextId": "ctx-456",
  "artifacts": [{
    "artifactId": "artifact-result-abc123",  // Required for identification
    "name": "result_name",  // Optional
    "parts": [
      {"kind": "text", "text": "..."},
      {"kind": "data", "data": {...}}
    ]
  }]
}

Verification

• ✅ Code reviewer agent searched all 26 documentation files with A2A references
• ✅ Fixed 10 total files (2 for requests, 8 for responses)
• ✅ All tests pass (schemas, examples, typecheck)
• ✅ All examples now match the A2A protocol specification
• ✅ Updated processing code to show proper artifactId usage

Impact

Eliminates confusion for developers implementing A2A clients:

• Request payloads now use correct field names and structure
• Response artifacts include required artifactId field
• All A2A documentation is consistent with protocol specification
• Developers can properly identify and track artifacts

Next Steps

Multi-artifact response examples (showing 2+ artifacts in one response) will be added in a separate PR to demonstrate when/how multiple artifacts are used for versioning, different output types, and incremental streaming.

[bokelley]

moving to 249