A2A 协议：跨平台 Agent 互操作标准深度解读

// A2A Agent Card 示例
// 通过 https://agent.example.com/.well-known/agent.json 访问
{
  "name": "代码审查 Agent",
  "description": "自动审查 PR 的代码质量、安全性和性能",
  "url": "https://agent.example.com/a2a",
  "version": "1.0.0",
  "capabilities": {
    "inputModes": ["text", "code"],
    "outputModes": ["text", "json"],
    "skills": [
      {
        "id": "code-review",
        "name": "代码审查",
        "description": "对代码进行质量审查，返回问题列表和修复建议",
        "inputSchema": {
          "language": "string",
          "code": "string",
          "reviewLevel": "basic | detailed | security"
        }
      }
    ]
  },
  "security": {
    "schemes": { "bearer": { "type": "http", "scheme": "bearer" } }
  }
}

// A2A Client 调用示例
async function delegateToAgent(
    agentUrl: string,
    task: string,
    skillId?: string
): Promise<string> {
    const response = await fetch(agentUrl, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/a2a+json',
            'Authorization': 'Bearer YOUR_TOKEN'
        },
        body: JSON.stringify({
            taskId: crypto.randomUUID(),
            message: {
                role: 'user',
                parts: [{ type: 'text', text: task }]
            },
            metadata: skillId ? { skillId } : undefined
        })
    });
    
    const result = await response.json();
    return result.status.message?.parts?.[0]?.text || '';
}

// 使用示例：委托代码审查任务
const review = await delegateToAgent(
    'https://code-review-agent.example.com/a2a',
    '审查以下 Python 代码的安全性',
    'code-review'
);

// A2A Task 完整类型定义
type TaskStatus = 'pending' | 'working' | 'completed' | 'failed' | 'canceled';

interface A2ATask {
    id: string;
    sessionId?: string;  // 多轮对话会话
    status: {
        state: TaskStatus;
        message?: {
            role: 'user' | 'agent';
            parts: Array<{
                type: 'text' | 'file' | 'data';
                text?: string;
            }>;
        };
        timestamp: string;
    };
    history?: any[];
    artifacts?: any[];
}

// Task 轮询示例
async function pollTaskStatus(
    taskUrl: string,
    maxAttempts = 30,
    intervalMs = 2000
): Promise<A2ATask> {
    for (let i = 0; i < maxAttempts; i++) {
        const response = await fetch(taskUrl, {
            headers: { 'Accept': 'application/a2a+json' }
        });
        const task: A2ATask = await response.json();
        
        if (task.status.state === 'completed') return task;
        if (task.status.state === 'failed')
            throw new Error('任务失败');
        if (task.status.state === 'canceled')
            throw new Error('任务已取消');
        
        await new Promise(r => setTimeout(r, intervalMs));
    }
    throw new Error('任务超时');
}

// A2A Server 实现（Node.js + Express）
import express from 'express';
import { randomUUID } from 'crypto';

const app = express();
app.use(express.json());

const tasks = new Map<string, any>();

// Agent Card 端点
app.get('/.well-known/agent.json', (_req, res) => {
    res.json({
        name: "代码审查 Agent",
        description: "自动审查代码质量、安全性和性能",
        url: "http://localhost:3000/a2a",
        version: "1.0.0",
        capabilities: {
            inputModes: ["text"],
            outputModes: ["text"],
            skills: [{
                id: "code-review",
                name: "代码审查",
                description: "审查代码返回问题列表"
            }]
        }
    });
});

// 创建任务端点
app.post('/a2a', async (req, res) => {
    const taskId = randomUUID();
    const task = {
        id: taskId,
        status: {
            state: 'working' as const,
            message: {
                role: 'agent' as const,
                parts: [{ type: 'text' as const, text: '正在审查...' }]
            },
            timestamp: new Date().toISOString()
        },
        history: [req.body.message]
    };
    
    // 异步执行审查
    executeReview(taskId, req.body.message.parts[0].text)
        .then(result => {
            tasks.get(taskId)!.status = {
                state: 'completed' as const,
                message: {
                    role: 'agent' as const,
                    parts: [{ type: 'text' as const, text: result }]
                },
                timestamp: new Date().toISOString()
            };
        });
    
    tasks.set(taskId, task);
    res.json(task);
});

// 查询任务状态
app.get('/a2a/:taskId', (req, res) => {
    const task = tasks.get(req.params.taskId);
    if (!task) return res.status(404).json({ error: 'Not found' });
    res.json(task);
});

async function executeReview(_id: string, code: string): Promise<string> {
    await new Promise(r => setTimeout(r, 3000));
    const issues: string[] = [];
    if (code.includes('eval(')) issues.push('⚠️ 使用 eval() 有注入风险');
    if (!code.includes('try ')) issues.push('💡 建议添加 try-catch');
    return issues.length === 0 ? '✅ 代码质量良好' : issues.join('\n');
}

app.listen(3000, () => console.log('A2A Server :3000'));

// 编排 Agent：跨部门工单处理
const DEPT_AGENTS = [
    { name: "IT", url: "https://it-agent.company.com/a2a", skills: ["设备配置"] },
    { name: "财务", url: "https://finance-agent.company.com/a2a", skills: ["预算审批"] },
    { name: "HR", url: "https://hr-agent.company.com/a2a", skills: ["员工录入"] }
];

async function handleOnboarding(employee: {name: string, dept: string, role: string}) {
    // 并行委托三个部门 Agent
    const results = await Promise.allSettled([
        delegateToAgent(DEPT_AGENTS[0].url, `为新员工 ${employee.name} 配置 IT 设备`),
        delegateToAgent(DEPT_AGENTS[1].url, `为 ${employee.name} 开通财务权限`),
        delegateToAgent(DEPT_AGENTS[2].url, `录入新员工 ${employee.name}`)
    ]);
    
    for (const [dept, result] of Object.entries({IT: results[0], 财务: results[1], HR: results[2]})) {
        if (result.status === 'fulfilled') {
            console.log(`${dept}: ${result.value}`);
        } else {
            console.error(`${dept}: 处理失败`);
        }
    }
}