项目简介

Artinet SDK 是一个基于 TypeScript 构建的库，旨在简化可互操作 AI Agent 的创建。它采用服务导向架构，允许开发者将 AI Agent 部署为简单的独立进程，或无缝嵌入到专用服务器中。该 SDK 完整实现了 Agent2Agent (A2A) 协议，并提供了一个 Model Context Protocol (MCP) 兼容层，使得 A2A Agent 能够作为完全符合 MCP 规范的服务器与 LLM 客户端通信。

主要功能点

MCP服务器能力： 能够将通过 Artinet SDK 构建的 Agent 封装成完整的 MCP 服务器，并通过 JSON-RPC 协议提供上下文信息和功能。
资源托管与数据访问： 支持托管和管理 资源 (Resources)，例如将 Agent 卡片 (AgentCard) 作为 'agent://card' URI 资源暴露给 LLM 客户端，提供标准化的数据访问能力。
工具注册与调用： 允许 LLM 客户端注册和执行 工具 (Tools)，以便调用 Agent 提供的外部功能，例如发送消息 ('send-message')、获取任务状态 ('get-task') 或取消任务 ('cancel-task')。
LLM交互模式： 虽然 MCP 定义中提到 Prompt 模板，但 Artinet SDK 主要通过 A2A 协议的消息 ('Message') 结构和其对 MCP 工具的映射来支持 LLM 交互，间接实现可定制的交互模式。
会话与状态管理： MCP 服务器负责会话管理和能力声明，支持持久化存储 Agent 任务状态。
多传输协议支持： 除了 MCP 兼容层支持 Stdio 传输协议外，基础的 A2A Agent 服务还支持 SSE (Server-Sent Events) 和 WebSockets 等多种传输协议。
模块化Agent构建： 提供 'AgentBuilder' 模式和直接 'AgentEngine' 实现，方便开发者灵活构建简单或多步骤的 AI Agent 逻辑。

安装步骤

Node.js 要求: 请确保您的系统已安装 Node.js (推荐 20 或 ≥ 22 版本)。

安装 Artinet SDK: 在您的项目根目录运行以下命令：

npm install @artinet/sdk

快速创建 Agent 项目 (可选): 如果您想快速开始一个新项目，可以使用 Artinet 的 'create-agent' 命令。它会为您提供多个项目模板：
```
npx @artinet/create-agent@latest
```

MCP服务器配置

当您的 Artinet SDK 实现的 Agent 作为 MCP 服务器运行时，MCP 客户端需要知道如何启动并连接到您的服务器。以下是一个典型的 JSON 格式配置示例，其中包含了 MCP 客户端连接时所需的基本信息：

{
  "name": "我的Artinet MCP Agent",
  "command": "node",
  "args": [
    "path/to/your/mcp_server_script.js",
    "--port", "4000",
    "--log-level", "info"
  ],
  "env": {
    "ARTINET_API_KEY": "YOUR_OPTIONAL_API_KEY"
  },
  "transport": "stdio"
}

参数注释:

'name': 您为 MCP 服务器实例指定的友好名称，有助于客户端识别。
'command': 用于启动 MCP 服务器进程的命令行命令。例如，对于 Node.js 应用程序通常是 '"node"'。
'args': 一个字符串数组，包含传递给 'command' 的命令行参数。
- 'path/to/your/mcp_server_script.js': 这是您实际创建和启动 Artinet SDK MCP Agent 的 Node.js 脚本文件路径。请替换为您的实际路径。
- '--port', '4000': （可选，取决于传输协议）如果您的 MCP 服务器通过 HTTP/WebSocket 监听网络端口，则指定监听端口。对于 Stdio 传输，此参数可能不直接使用，但仍可作为脚本的内部配置。
- '--log-level', 'info': （可选）配置服务器的日志输出级别，如 'info'、'debug'、'error' 等。
'env': （可选）一个键值对对象，用于在启动服务器进程时设置环境变量。
'transport': MCP 服务器与客户端通信所使用的传输协议。'"stdio"' 表示通过标准输入/输出进行通信，这是 'StdioServerTransport' 的默认方式。其他可能的传输包括 '"websocket"' 或 '"sse"'（需要相应的实现和配置）。

基本使用方法 (MCP服务器)

要将您使用 Artinet SDK 构建的 A2A Agent 暴露为 MCP 服务器，您需要遵循以下核心步骤：

定义您的 Agent 逻辑: 首先，使用 'AgentBuilder' 或直接实现 'AgentEngine' 接口来定义您的 Agent 如何处理传入的消息和任务。这是 Agent 的核心行为。

// my-a2a-agent-logic.js
import { AgentBuilder, createAgent } from "@artinet/sdk";

const myAgentEngine = AgentBuilder()
  .text(async ({ content: userInput, context }) => {
    // 您的 Agent 逻辑，例如：
    console.log('Agent 收到消息: ${userInput}');
    return 'MCP Agent 响应: 您好，您说的是 "${userInput}"';
  })
  .createAgentEngine();

export const a2aAgentInstance = createAgent({
  engine: myAgentEngine,
  agentCard: {
    name: "我的Artinet MCP Agent",
    url: "http://localhost:3000/a2a", // A2A的URL，即使通过MCP暴露也可能有
    version: "1.0.0",
    protocolVersion: "0.3.0",
    description: "一个通过Artinet SDK暴露的MCP Agent。",
    capabilities: { streaming: true },
    skills: [{ id: "echo", name: "Echo 功能" }],
    defaultInputModes: ["text"],
    defaultOutputModes: ["text"]
  },
});

创建 MCP Agent 实例并连接传输协议: 在另一个脚本中（例如 'mcp_server_script.js'），导入您的 A2A Agent 实例，并使用 'createMCPAgent' 将其封装成一个 MCP Agent。然后，选择并连接一个 MCP 传输协议，例如 'StdioServerTransport'。

// mcp_server_script.js
import { createMCPAgent } from "@artinet/sdk";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { a2aAgentInstance } from "./my-a2a-agent-logic.js"; // 导入您上面定义的A2A Agent

async function startMCPServer() {
  // 创建 MCP Agent 实例，封装现有的 A2A Agent
  const mcpAgent = createMCPAgent({
    serverInfo: {
      name: "我的Artinet MCP Agent", // MCP 服务器的名称
      version: "1.0.0",
    },
    agent: a2aAgentInstance, // 使用您创建的A2A Agent实例
    agentCardUri: "agent://card", // 定义Agent Card的URI
  });

  // 您可以注册额外的 MCP 工具（Artinet SDK 会默认注册一些基础工具）
  mcpAgent.registerTool({
    name: "custom-query",
    description: "一个自定义的查询工具，仅用于演示。",
    parameters: {
      type: "object",
      properties: {
        query: { type: "string", description: "要查询的字符串。" },
      },
    },
    execute: async ({ query }) => {
      return {
        contentType: "text/plain",
        content: 'MCP自定义工具收到查询: ${query}',
      };
    },
  });

  // 连接 Stdio 传输协议，通过标准输入/输出与 MCP 客户端通信
  await mcpAgent.connect(new StdioServerTransport());

  console.log("Artinet MCP Agent 服务器已通过 Stdio 启动，等待 MCP 客户端连接...");
}

startMCPServer().catch(console.error);

运行 MCP 服务器: 在命令行中运行您的 'mcp_server_script.js'：
```
node mcp_server_script.js
```
此时，您的 Artinet SDK MCP 服务器将通过标准输入/输出启动并等待 MCP 客户端的连接。

MCP 客户端交互示例 (概念性): 一个 MCP 客户端可以通过 JSON-RPC 协议与您的 Artinet MCP 服务器进行交互。

读取 Agent 卡片 (资源): 客户端发送的 JSON-RPC 请求:

{
  "jsonrpc": "2.0",
  "method": "readResource",
  "params": {
    "uri": "agent://card"
  },
  "id": 1
}

服务器将响应包含 Agent 卡片详情的 JSON。

调用 'send-message' 工具: 客户端发送的 JSON-RPC 请求:

{
  "jsonrpc": "2.0",
  "method": "callTool",
  "params": {
    "name": "send-message",
    "arguments": {
      "message": {
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "Hello from MCP client!"
          }
        ]
      }
    }
  },
  "id": 2
}

服务器将返回 'send-message' 工具处理后的结果。

调用自定义工具 'custom-query': 客户端发送的 JSON-RPC 请求:

{
  "jsonrpc": "2.0",
  "method": "callTool",
  "params": {
    "name": "custom-query",
    "arguments": {
      "query": "What is the capital of France?"
    }
  },
  "id": 3
}

服务器将返回 'custom-query' 工具处理后的结果。

关键词

AI Agent, LLM集成, 上下文服务, 工具调用, 资源管理

Artinet SDK

项目简介

主要功能点

安装步骤

MCP服务器配置

基本使用方法 (MCP服务器)

关键词

服务器信息