A2A JS SDK 完整教程：快速入门指南

张成AI2025-06-10 10:34

目录

  1. [什么是 A2A JS SDK?](#什么是 A2A JS SDK?)
  2. [A2A JS 安装与设置](#A2A JS 安装与设置)
  3. [A2A JS 核心概念](#A2A JS 核心概念)
  4. [创建你的第一个 A2A JS 代理](#创建你的第一个 A2A JS 代理)
  5. [A2A JS 服务端开发](#A2A JS 服务端开发)
  6. [A2A JS 客户端使用](#A2A JS 客户端使用)
  7. [A2A JS 高级特性](#A2A JS 高级特性)
  8. [A2A JS 最佳实践](#A2A JS 最佳实践)
  9. [A2A JS 故障排除](#A2A JS 故障排除)

什么是 A2A JS SDK?

A2A JS SDK 是一个专为 JavaScript/TypeScript 开发者设计的强大库，用于构建符合 Agent2Agent (A2A) 协议 的智能代理应用程序。这个 AA2A JS 框架让开发者能够轻松创建能够相互通信和协作的智能代理系统。

A2A JS 的核心优势

  • 🚀 简单易用 : A2A JS 提供直观的 API，让开发者能快速上手
  • 🔄 实时通信: 支持流式处理和服务端推送事件 (SSE)
  • 🛡️ 类型安全: 基于 TypeScript 构建，提供完整的类型支持
  • 🌐 跨平台 : *A2A JS 可在 Node.js 和浏览器环境中运行
  • 📡 标准协议: 完全实现 A2A 协议规范

A2A JS 安装与设置

安装 A2A JS SDK

使用 npm 安装 A2A JS SDK：

bash 复制代码 
npm install a2a-sdk

或者使用 yarn：

bash 复制代码 
yarn add a2a-sdk

验证 A2A JS 安装

创建一个简单的测试文件来验证 A2A JS 是否正确安装：

typescript 复制代码 
import { A2AClient, AgentCard } from "a2a-sdk";

console.log("A2A JS SDK 安装成功！");

A2A JS 核心概念

在开始使用 A2A JS 之前，了解以下核心概念很重要：

1. Agent Card (代理卡片)

A2A JS 中的每个代理都需要一个 Agent Card，它描述了代理的能力和接口：

typescript 复制代码 
import { AgentCard } from "a2a-sdk";

const agentCard: AgentCard = {
  name: 'My A2A JS Agent',
  description: '使用 A2A JS SDK 构建的智能代理',
  url: 'http://localhost:3000/',
  provider: {
    organization: 'A2A JS Developers',
    url: 'https://example.com'
  },
  version: '1.0.0',
  capabilities: {
    streaming: true,
    pushNotifications: false,
    stateTransitionHistory: true,
  },
  skills: [{
    id: 'general_chat',
    name: '通用对话',
    description: '使用 A2A JS 进行通用对话',
    tags: ['chat', 'a2a-js'],
    examples: ['你好', '帮我解答问题']
  }]
};

2. Agent Executor (代理执行器)

A2A JS 的核心执行逻辑通过 AgentExecutor 实现：

typescript 复制代码 
import { AgentExecutor, RequestContext, IExecutionEventBus } from "a2a-sdk";

class MyA2AJSExecutor implements AgentExecutor {
  async execute(
    requestContext: RequestContext,
    eventBus: IExecutionEventBus
  ): Promise<void> {
    // 你的 A2A JS 代理逻辑
    console.log("A2A JS 代理正在处理请求...");
  }

  async cancelTask(taskId: string, eventBus: IExecutionEventBus): Promise<void> {
    console.log(`A2A JS 取消任务: ${taskId}`);
  }
}

创建你的第一个 A2A JS 代理

让我们使用 A2A JS SDK 创建一个完整的代理示例：

步骤 1: 定义 A2A JS 代理卡片

typescript 复制代码 
import { AgentCard } from "a2a-sdk";

const myAgentCard: AgentCard = {
  name: 'Hello World A2A JS Agent',
  description: '我的第一个 A2A JS 代理，用于学习 A2A JS SDK',
  url: 'http://localhost:3000/',
  provider: {
    organization: 'A2A JS Tutorial',
    url: 'https://example.com'
  },
  version: '1.0.0',
  capabilities: {
    streaming: true,
    pushNotifications: false,
    stateTransitionHistory: true,
  },
  defaultInputModes: ['text/plain'],
  defaultOutputModes: ['text/plain'],
  skills: [{
    id: 'hello_world',
    name: 'Hello World',
    description: 'A2A JS 示例技能：回复问候',
    tags: ['hello', 'greeting', 'a2a-js'],
    examples: [
      '你好',
      'Hello',
      '介绍一下 A2A JS'
    ],
    inputModes: ['text/plain'],
    outputModes: ['text/plain']
  }],
  supportsAuthenticatedExtendedCard: false,
};

步骤 2: 实现 A2A JS 执行器

typescript 复制代码 
import {
  AgentExecutor,
  RequestContext,
  IExecutionEventBus,
  Task,
  TaskState,
  TaskStatusUpdateEvent
} from "a2a-sdk";
import { v4 as uuidv4 } from "uuid";

class HelloWorldA2AJSExecutor implements AgentExecutor {
  private cancelledTasks = new Set<string>();

  async cancelTask(taskId: string, eventBus: IExecutionEventBus): Promise<void> {
    this.cancelledTasks.add(taskId);
    console.log(`A2A JS 执行器取消任务: ${taskId}`);
  }

  async execute(
    requestContext: RequestContext,
    eventBus: IExecutionEventBus
  ): Promise<void> {
    const userMessage = requestContext.userMessage;
    const existingTask = requestContext.task;
    
    const taskId = existingTask?.id || uuidv4();
    const contextId = userMessage.contextId || existingTask?.contextId || uuidv4();

    console.log(`A2A JS 代理处理消息: ${userMessage.parts[0]?.text}`);

    // 创建新任务
    if (!existingTask) {
      const initialTask: Task = {
        kind: 'task',
        id: taskId,
        contextId: contextId,
        status: {
          state: TaskState.Submitted,
          timestamp: new Date().toISOString(),
        },
        history: [userMessage],
        metadata: userMessage.metadata,
        artifacts: [],
      };
      eventBus.publish(initialTask);
    }

    // 发布工作状态
    const workingUpdate: TaskStatusUpdateEvent = {
      kind: 'status-update',
      taskId: taskId,
      contextId: contextId,
      status: {
        state: TaskState.Working,
        message: {
          kind: 'message',
          role: 'agent',
          messageId: uuidv4(),
          parts: [{ kind: 'text', text: 'A2A JS 代理正在思考...' }],
          taskId: taskId,
          contextId: contextId,
        },
        timestamp: new Date().toISOString(),
      },
      final: false,
    };
    eventBus.publish(workingUpdate);

    // 模拟处理时间
    await new Promise(resolve => setTimeout(resolve, 1000));

    // 检查取消状态
    if (this.cancelledTasks.has(taskId)) {
      const cancelledUpdate: TaskStatusUpdateEvent = {
        kind: 'status-update',
        taskId: taskId,
        contextId: contextId,
        status: {
          state: TaskState.Canceled,
          timestamp: new Date().toISOString(),
        },
        final: true,
      };
      eventBus.publish(cancelledUpdate);
      return;
    }

    // 生成响应
    const userText = userMessage.parts[0]?.text || '';
    let responseText = '';
    
    if (userText.toLowerCase().includes('hello') || userText.includes('你好')) {
      responseText = `你好！欢迎使用 A2A JS SDK！我是用 A2A JS 构建的智能代理。`;
    } else if (userText.toLowerCase().includes('a2a js')) {
      responseText = `A2A JS SDK 是一个强大的 JavaScript 库，用于构建智能代理应用程序！`;
    } else {
      responseText = `我是一个 A2A JS 代理，收到了你的消息："${userText}"。感谢使用 A2A JS SDK！`;
    }

    // 发布最终结果
    const finalUpdate: TaskStatusUpdateEvent = {
      kind: 'status-update',
      taskId: taskId,
      contextId: contextId,
      status: {
        state: TaskState.Completed,
        message: {
          kind: 'message',
          role: 'agent',
          messageId: uuidv4(),
          parts: [{ kind: 'text', text: responseText }],
          taskId: taskId,
          contextId: contextId,
        },
        timestamp: new Date().toISOString(),
      },
      final: true,
    };
    eventBus.publish(finalUpdate);
  }
}

步骤 3: 启动 A2A JS 服务器

typescript 复制代码 
import express from 'express';
import {
  A2AExpressApp,
  DefaultRequestHandler,
  InMemoryTaskStore
} from "a2a-sdk";

const taskStore = new InMemoryTaskStore();
const agentExecutor = new HelloWorldA2AJSExecutor();

const requestHandler = new DefaultRequestHandler(
  myAgentCard,
  taskStore,
  agentExecutor
);

const appBuilder = new A2AExpressApp(requestHandler);
const expressApp = appBuilder.setupRoutes(express(), '');

const PORT = process.env.PORT || 3000;
expressApp.listen(PORT, () => {
  console.log(`A2A JS 代理服务器启动在 http://localhost:${PORT}`);
  console.log(`A2A JS 代理卡片: http://localhost:${PORT}/.well-known/agent.json`);
  console.log('按 Ctrl+C 停止 A2A JS 服务器');
});

A2A JS 服务端开发

任务存储

A2A JS 提供了内存任务存储，你也可以实现自定义存储：

typescript 复制代码 
import { TaskStore, Task } from "a2a-sdk";

class CustomA2AJSTaskStore implements TaskStore {
  private tasks = new Map<string, Task>();

  async getTask(taskId: string): Promise<Task | undefined> {
    console.log(`A2A JS 获取任务: ${taskId}`);
    return this.tasks.get(taskId);
  }

  async setTask(task: Task): Promise<void> {
    console.log(`A2A JS 保存任务: ${task.id}`);
    this.tasks.set(task.id, task);
  }

  async deleteTask(taskId: string): Promise<void> {
    console.log(`A2A JS 删除任务: ${taskId}`);
    this.tasks.delete(taskId);
  }
}

中间件支持

A2A JS 基于 Express.js，支持所有标准中间件：

typescript 复制代码 
import cors from 'cors';
import express from 'express';

const app = express();

// A2A JS 服务器中间件配置
app.use(cors());
app.use(express.json());

// 自定义 A2A JS 日志中间件
app.use((req, res, next) => {
  console.log(`A2A JS 请求: ${req.method} ${req.path}`);
  next();
});

A2A JS 客户端使用

基础客户端操作

typescript 复制代码 
import { A2AClient, MessageSendParams } from "a2a-sdk";
import { v4 as uuidv4 } from "uuid";

const client = new A2AClient("http://localhost:3000");

async function testA2AJSClient() {
  console.log("测试 A2A JS 客户端...");
  
  const messageParams: MessageSendParams = {
    message: {
      messageId: uuidv4(),
      role: "user",
      parts: [{ kind: "text", text: "你好，A2A JS！" }],
      kind: "message"
    },
    configuration: {
      blocking: true,
      acceptedOutputModes: ['text/plain']
    }
  };

  try {
    const response = await client.sendMessage(messageParams);
    
    if (response.error) {
      console.error("A2A JS 客户端错误:", response.error);
      return;
    }

    console.log("A2A JS 响应:", response.result);
  } catch (error) {
    console.error("A2A JS 通信错误:", error);
  }
}

testA2AJSClient();

A2A JS 流式处理

A2A JS 支持实时流式通信：

typescript 复制代码 
import { A2AClient, TaskStatusUpdateEvent } from "a2a-sdk";

async function streamA2AJSResponse() {
  const client = new A2AClient("http://localhost:3000");
  
  console.log("开始 A2A JS 流式处理...");
  
  const streamParams = {
    message: {
      messageId: uuidv4(),
      role: "user",
      parts: [{ kind: "text", text: "使用 A2A JS 进行流式对话" }],
      kind: "message"
    }
  };

  try {
    const stream = client.sendMessageStream(streamParams);
    
    for await (const event of stream) {
      if (event.kind === 'task') {
        console.log(`A2A JS 任务创建: ${event.id}`);
      } else if (event.kind === 'status-update') {
        const statusEvent = event as TaskStatusUpdateEvent;
        console.log(`A2A JS 状态更新: ${statusEvent.status.state}`);
        
        if (statusEvent.status.message?.parts[0]?.text) {
          console.log(`A2A JS 消息: ${statusEvent.status.message.parts[0].text}`);
        }
        
        if (statusEvent.final) {
          console.log("A2A JS 流式处理完成");
          break;
        }
      }
    }
  } catch (error) {
    console.error("A2A JS 流式处理错误:", error);
  }
}

A2A JS 高级特性

工件处理

A2A JS 支持工件（Artifacts）的创建和管理：

typescript 复制代码 
import { TaskArtifactUpdateEvent } from "a2a-sdk";

// 在 AgentExecutor 中发布工件
const artifactUpdate: TaskArtifactUpdateEvent = {
  kind: 'artifact-update',
  taskId: taskId,
  contextId: contextId,
  artifact: {
    artifactId: "a2a-js-example",
    name: "A2A JS 示例文件",
    parts: [{ 
      text: `# A2A JS 生成的内容\n\n这是使用 A2A JS SDK 生成的示例文件。`
    }],
  },
  append: false,
  lastChunk: true,
};
eventBus.publish(artifactUpdate);

安全配置

为 A2A JS 代理配置安全选项：

typescript 复制代码 
const secureAgentCard: AgentCard = {
  name: 'Secure A2A JS Agent',
  description: '安全的 A2A JS 代理',
  // ... 其他配置
  securitySchemes: {
    apiKey: {
      type: 'apiKey',
      name: 'X-API-Key',
      in: 'header'
    }
  },
  security: [{
    apiKey: []
  }]
};

A2A JS 最佳实践

1. 错误处理

在 A2A JS 应用中实施全面的错误处理：

typescript 复制代码 
class RobustA2AJSExecutor implements AgentExecutor {
  async execute(requestContext: RequestContext, eventBus: IExecutionEventBus) {
    try {
      // A2A JS 执行逻辑
      await this.processRequest(requestContext, eventBus);
    } catch (error) {
      console.error("A2A JS 执行错误:", error);
      
      // 发布错误状态
      const errorUpdate: TaskStatusUpdateEvent = {
        kind: 'status-update',
        taskId: requestContext.task?.id || uuidv4(),
        contextId: requestContext.userMessage.contextId || uuidv4(),
        status: {
          state: TaskState.Failed,
          message: {
            kind: 'message',
            role: 'agent',
            messageId: uuidv4(),
            parts: [{ kind: 'text', text: 'A2A JS 处理时发生错误，请稍后重试。' }],
          },
          timestamp: new Date().toISOString(),
        },
        final: true,
      };
      eventBus.publish(errorUpdate);
    }
  }
}

2. 性能优化

优化你的 A2A JS 应用性能：

typescript 复制代码 
// 使用连接池优化 A2A JS 客户端
const client = new A2AClient("http://localhost:3000", {
  keepAlive: true,
  timeout: 30000
});

// A2A JS 代理响应缓存
class CachedA2AJSExecutor implements AgentExecutor {
  private cache = new Map<string, string>();
  
  async execute(requestContext: RequestContext, eventBus: IExecutionEventBus) {
    const userText = requestContext.userMessage.parts[0]?.text || '';
    const cacheKey = `a2a-js-${userText}`;
    
    // 检查 A2A JS 缓存
    if (this.cache.has(cacheKey)) {
      console.log("A2A JS 使用缓存响应");
      // 返回缓存的响应
    }
    
    // 处理新请求并缓存结果
  }
}

3. 日志记录

为 A2A JS 应用添加详细的日志记录：

typescript 复制代码 
import { createLogger, format, transports } from 'winston';

const a2aJSLogger = createLogger({
  level: 'info',
  format: format.combine(
    format.timestamp(),
    format.printf(({ timestamp, level, message }) => {
      return `[A2A JS] ${timestamp} ${level}: ${message}`;
    })
  ),
  transports: [
    new transports.Console(),
    new transports.File({ filename: 'a2a-js.log' })
  ]
});

// 在 A2A JS 代码中使用
a2aJSLogger.info('A2A JS 代理启动成功');
a2aJSLogger.error('A2A JS 处理错误', { error: errorDetails });

A2A JS 故障排除

常见问题解决

1. A2A JS 连接问题
typescript 复制代码 
// 检查 A2A JS 服务器连接
async function checkA2AJSConnection() {
  try {
    const client = new A2AClient("http://localhost:3000");
    const response = await fetch("http://localhost:3000/.well-known/agent.json");
    
    if (response.ok) {
      console.log("A2A JS 服务器连接正常");
    } else {
      console.error("A2A JS 服务器响应异常:", response.status);
    }
  } catch (error) {
    console.error("A2A JS 连接失败:", error);
  }
}

也可以尝试如下方法：

2. A2A JS 类型错误

确保正确导入 A2A JS 类型：

typescript 复制代码 
// 正确的 A2A JS 类型导入
import {
  AgentCard,
  AgentExecutor,
  A2AClient,
  Task,
  TaskState,
  Message,
  MessageSendParams
} from "a2a-sdk";
3. A2A JS 性能调试
typescript 复制代码 
// A2A JS 性能监控
class PerformanceA2AJSExecutor implements AgentExecutor {
  async execute(requestContext: RequestContext, eventBus: IExecutionEventBus) {
    const startTime = Date.now();
    console.log(`A2A JS 开始处理: ${startTime}`);
    
    try {
      // 你的 A2A JS 逻辑
      await this.processRequest(requestContext, eventBus);
    } finally {
      const endTime = Date.now();
      console.log(`A2A JS 处理完成，耗时: ${endTime - startTime}ms`);
    }
  }
}

总结

A2A JS SDK 是构建智能代理应用程序的强大工具。通过本教程，你已经学习了：

  • A2A JS 的核心概念和架构
  • 如何创建和配置 A2A JS 代理
  • A2A JS 服务端和客户端开发
  • A2A JS 的高级特性和最佳实践
  • A2A JS 应用的故障排除方法

现在你可以开始构建自己的 A2A JS 应用程序了！记住，A2A JS SDK 提供了丰富的功能来帮助你创建强大、可扩展的智能代理系统。

如需更多 A2A JS 资源和示例，请访问：

开始你的 A2A JS 开发之旅吧！🚀

A2A JS

相关推荐
锈儿海老师20 分钟前
AST 工具大PK！Biome 的 GritQL 插件 vs. ast-grep，谁是你的菜？
前端·javascript·eslint
令狐寻欢22 分钟前
JavaScript中 的 Object.defineProperty 和 defineProperties
javascript
快起来别睡了23 分钟前
代理模式：送花风波
前端·javascript·架构
FogLetter43 分钟前
从add函数类型判断说起：NaN的奇幻漂流与JS数据类型的奥秘
前端·javascript
兰贝达1 小时前
商品SKU选择器实现思路，包简单
前端·javascript·vue.js
程序员小张丶2 小时前
React Native在HarmonyOS 5.0阅读类应用开发中的实践
javascript·react native·react.js·阅读·harmonyos5.0
EndingCoder2 小时前
React Native 是什么？为什么学它？
javascript·react native·react.js
摸鱼仙人~2 小时前
Redux Toolkit 快速入门指南：createSlice、configureStore、useSelector、useDispatch 全面解析
开发语言·javascript·ecmascript
程序员小张丶3 小时前
基于React Native开发HarmonyOS 5.0主题应用技术方案
javascript·react native·react.js·主题·harmonyos5.0
teeeeeeemo3 小时前
Vue数据响应式原理解析
前端·javascript·vue.js·笔记·前端框架·vue
热门推荐
01【图像处理与机器视觉】XJTU期末考点02从零安装 LLaMA-Factory 微调 Qwen 大模型成功及所有的坑03KGG转MP3工具|非KGM文件|解密音频04Coze扣子平台完整体验和实践（附国内和国际版对比）05YOLOv8入门 | 重要性能衡量指标、训练结果评价及分析及影响mAP的因素【发论文关注的指标】06【SpeedAI科研小助手】2分钟极速解决知网维普重复率、AIGC率过高，一键全文降！文件格式不变，公式都保留的！07零代码入门 | Coze——让大模型接入自己的数据库08海康Visionmaster-常见问题排查方法-启动阶段09DeepSeek各版本说明与优缺点分析10R-tree详解