Overview

This PR completes the migration of the Agent Development Kit (ADK) to the A2A (Agent-to-Agent) Protocol Schema v0.3.0. The migration addresses breaking changes in the protocol specification, including the new Part type system, typed role constants, and state-based task management.

Breaking Changes

1. Part Type System Migration

Before (Interface-based discriminated union):

message := types.Message{
    Role: "user",
    Parts: []types.Part{
        types.TextPart{
            Kind: "text",
            Text: "Hello",
        },
    },
}

// Access via type assertion
if textPart, ok := part.(types.TextPart); ok {
    fmt.Println(textPart.Text)
}

After (Struct with optional fields and helper functions):

message := types.Message{
    Role: types.RoleUser,
    Parts: []types.Part{
        types.CreateTextPart("Hello"),
    },
}

// Access via field check
if part.Text != nil {
    fmt.Println(*part.Text)
}

2. Role Type System

Before (String literals):

Role: "user"
Role: "assistant"

After (Typed constants):

Role: types.RoleUser        // "ROLE_USER"
Role: types.RoleAgent       // "ROLE_AGENT"
Role: types.RoleUnspecified // "ROLE_UNSPECIFIED"

Note: A2A protocol has NO ROLE_SYSTEM - system prompts are agent configuration, not messages.

3. Input-Required State Management

Before (Checking non-existent Kind field):

if msg.Kind == "input_required" {  // ❌ Field doesn't exist!
    // handle input required
}

After (State-based checking):

if task.Status.State == types.TaskStateInputRequired {
    // Task is paused waiting for user input
    // Check task.Status.Message for the prompt sent to user
}

4. Message Converter Role Mapping

Established proper bidirectional mapping between A2A protocol (typed roles) and OpenAI SDK (string roles):

A2A → SDK:

• types.RoleUser → sdk.User
• types.RoleAgent → sdk.Assistant (or sdk.Tool if tool_call_id present)
• types.RoleUnspecified → sdk.User

SDK → A2A:

• "user" → types.RoleUser
• "assistant", "tool", "system" → types.RoleAgent

Files Changed

Core SDK Files

• server/utils/message_converter.go: Updated role mapping between A2A and OpenAI SDK formats, removed legacy string literal support

Example Files (30+ files updated)

AI-Powered Examples:

• examples/ai-powered/client/main.go
• examples/ai-powered/server/main.go
• examples/ai-powered-streaming/client/main.go
• examples/ai-powered-streaming/server/main.go

Input-Required Examples:

• examples/input-required/non-streaming/client/main.go
• examples/input-required/non-streaming/server/main.go
• examples/input-required/streaming/client/main.go
• examples/input-required/streaming/server/main.go

Artifact Examples:

• examples/artifacts-autonomous-tool/server/main.go
• examples/artifacts-filesystem/server/main.go
• examples/artifacts-minio/server/main.go
• examples/artifacts-with-default-handlers/server/main.go

Other Examples:

• examples/callbacks/server/main.go
• examples/default-handlers/server/main.go
• examples/minimal/server/main.go
• examples/queue-storage/in-memory/server/main.go
• examples/queue-storage/redis/server/main.go
• examples/static-agent-card/server/main.go
• examples/streaming/client/main.go
• examples/streaming/server/main.go
• examples/tls-server/server/main.go

Configuration:

• .markdownlint-cli2.jsonc: Updated line length from 80 to 140 characters

Key Fixes

1. Part Construction

• Replaced manual struct construction with helper functions:
  • types.CreateTextPart(text)
  • types.CreateDataPart(data, mimeType)
  • types.CreateFilePart(file)

2. Part Access Patterns

• Changed from type assertions to field presence checks:
  • if part.Text != nil { *part.Text }
  • if part.File != nil { part.File.Name }
  • if part.Data != nil { part.Data.MimeType }

3. Role Usage

• Enforced typed role constants throughout all examples
• Maintained OpenAI SDK compatibility in internal converter

4. Input-Required Flow

• Fixed fundamental misunderstanding in input-required examples:
  • Input-required is a task state, not a message property
  • Context determined by examining task.Status.Message
  • Removed fragile text pattern matching

5. Streaming Event Processing

• Fixed event discrimination to use field presence:
  • Check task.Status.Message != nil instead of task.Kind == "task"
  • Check statusUpdate.TaskID != "" instead of statusUpdate.Kind != "status-update"

Testing

All verification steps completed successfully:

✅ Code Quality:

task lint           # 0 issues found
task lint:examples  # 0 issues found

✅ Tests:

task test  # All tests passing

✅ Examples:

• All 30+ example applications build successfully
• Docker builds verified for all examples
• Integration tests passing

Migration Guide

For users upgrading to A2A v0.3.0:

1. Update Part construction:

   // Old
   types.TextPart{Kind: "text", Text: "message"}
   
   // New
   types.CreateTextPart("message")

2. Update Role usage:

   // Old
   Role: "user"
   Role: "assistant"
   
   // New
   Role: types.RoleUser
   Role: types.RoleAgent

3. Update Part access:

   // Old
   if textPart, ok := part.(types.TextPart); ok {
       text := textPart.Text
   }
   
   // New
   if part.Text != nil {
       text := *part.Text
   }

4. Update input-required handling:

   // Old
   if msg.Kind == "input_required" { ... }
   
   // New
   if task.Status.State == types.TaskStateInputRequired {
       prompt := getMessageText(task.Status.Message)
   }

TODOs

• Regression - ensure examples are still working as expected
• Docs - ensure documentation is up to date