Identity

身份

欢迎来到Identity代码仓库

---

AGNTCY Identity 通过开放和去中心化的技术，提供安全且可验证的方法，为 Agent 分配唯一身份。每个 Agent 都会被分配一个全球唯一标识符，并由可验证凭证（VC）提供支持。 AGNTCY Identity 支持使用自有身份，可以采用身份提供商（例如 Okta）分配的 ID 或 Agent Card（例如 Google 的 A2A）等约定，也可以按照标准（例如 W3C DID）分配 ID。 无论采用哪种身份分配方式，此组件都能确保 AGNTCY 生态系统中的每个 Agent 都拥有可验证的全球唯一身份，从而在不同的多 Agent 系统间实现安全认证、可信通信和互操作性。

• ID 与 ResolverMetadata 对象关联，以便安全、自动地进行验证。
• ID 可以关联一个或多个 Agent Badge。为什么？多个徽章可以针对不同系统提供细致且特定于任务的访问权限，避免赋予 Agent 过多权限。Agent Badge 包含可验证凭证（VC），其中包括：
  • Agent 的 ID
  • Schema 定义（例如 OASF）
  • 用于认证和其他安全需求的元数据。

说明

同样的结构也适用于 MCP 服务和 MAS，确保 IoA 中所有承载身份的实体保持一致。

📚 目录

• 🚀 设计 Agentic Trust
• 🌟 功能与主要组件
• ⚡️ 快速开始（5 分钟）
• 📜 查看 CLI 的核心命令
• 🧪 运行演示

你还可以：

• 📖 查看完整的 CLI 和 Node 文档
• 📦 查看示例 Agent 和 MCP 服务
• 📘 浏览完整的文档，了解我们平台的功能
• 📝 深入了解我们的 API 规范，获取详细的 API 文档

🚀 构建可信的 Agent 系统

• 核心原则：信任是 Agent 互联网的基础。
• 以身份为根基：AGNTCY Identity 确保 Agent 和工具（MCP 服务）均可验证其真实性。
• 灵活且可互操作：BYOID（自带身份），可与现有身份提供商（IdP）集成。

软件 Agent 之间安全可靠的通信，是 Agent 互联网（IoA）愿景的基石。 缺乏适当的身份管理，恶意或未经验证的 Agent 可能会渗透到多 Agent 系统（MAS）中，导致错误信息、欺诈或安全漏洞。 为降低这些风险，AGNTCY 提供了一个标准化且一致的框架，用于验证 Agent 身份并核验相关元数据。 这同样适用于：

• Agent
• 模型上下文协议（MCP）服务
• MAS（多 Agent 系统）

提示

此仓库包含一个 AI Agent 和 MCP 服务，用于展示 AGNTCY Identity 组件的实际应用！

🌟 功能与主要组件

功能

• 身份创建：为 Agent 和 MCP 服务生成唯一且可验证的身份。
• 现有身份接入：集成来自外部 IdP 的身份。
• 徽章创建与验证：验证 Agent 和 MCP 服务，并核验元数据。

主要组件

• Issuer CLI：通过命令行界面管理身份、保险库和凭证。
• Node Backend：用于身份管理和元数据管理的后端服务。

⚡️ 5 分钟快速入门

本简短指南将帮助你设置 Identity Issuer CLI 和 Identity Node Backend。 Issuer CLI 可为 Agent 和 MCP 服务生成、注册、搜索和验证徽章。该 CLI 包含一个库，可将用于签署徽章的密钥存储并取回，既支持本地存储，也支持使用第三方钱包或保险库。 Node Backend 包含 API 和后端核心。它负责存储、维护并绑定 org:sub-org ID、PubKeys、Subject ID 和元数据，其中包括徽章、ResolverMetadata 和可验证凭证（VC）。

先决条件

要顺利完成以下步骤，你需要安装：

• Docker Desktop，或同时安装：Docker Engine v27 或更高版本和 Docker Compose v2.35 或更高版本

步骤 1：安装 Issuer CLI

使用以下命令安装 Issuer CLI：

使用 curl：

sh -c "$(curl -sSL https://raw.githubusercontent.com/agntcy/identity/refs/heads/main/deployments/scripts/identity/install_issuer.sh)"

或使用 wget：

sh -c "$(wget -qO- https://raw.githubusercontent.com/agntcy/identity/refs/heads/main/deployments/scripts/identity/install_issuer.sh)"

说明

你也可以从最新发布版本下载适用于你平台的 Issuer CLI 二进制文件。

在某些平台上，你可能需要添加执行权限，和/或在 System Security Settings 中批准该二进制文件。

为了方便使用，可以考虑将该二进制文件移至 $PATH 或 /usr/local/bin 文件夹。

如果你已在本地配置 Golang，也可以使用 go install command：

go install github.com/agntcy/identity/cmd/issuer@latest && \
  ln -s $(go env GOPATH)/bin/issuer $(go env GOPATH)/bin/identity

步骤 2：使用 Docker 启动 Node Backend

1. 克隆仓库并进入 identity 目录：

   git clone https://github.com/agntcy/identity.git && cd identity
   

2. 使用 Docker 启动 Node Backend：

   ./deployments/scripts/identity/launch_node.sh
   

   如果本地已安装 make，也可以使用：

   make start_node
   

说明

你也可以使用我们的 helm chart 安装 Node Backend，相关说明请参阅 chart's 目录。

步骤 3：验证安装

运行以下命令，即可验证安装并查看可用命令：

identity -h

📜 CLI 核心命令

以下是可在 CLI 中使用的核心命令

• vault：管理加密保险库和密钥
• issuer：注册和管理发行方配置
• metadata：为身份生成和管理元数据
• badge：为身份颁发和发布徽章
• verify：验证身份徽章
• config：显示当前配置上下文

🧪 运行演示

此演示场景将帮助你了解如何在真实环境中使用 AGNTCY Identity 组件。 你将能够执行以下操作：

• 注册为发行方
• 为 MCP 服务生成元数据
• 为 MCP 服务颁发并发布徽章
• 验证已发布的徽章

前置条件

首先，按照上方 5 分钟快速入门部分中的步骤安装 Issuer CLI 并运行 Node Backend，然后生成本地保险库和密钥。

要在本地运行此演示环境，需要安装以下项目：

• Docker Desktop，或同时安装：Docker Engine v27 or higher 和 Docker Compose v2.35 or higher
• Ollama CLI
• Okta CLI

第 1 步：使用 Ollama 和 Docker 运行示例

示例中的 Agent 依赖本地运行的 Llama 3.2 大模型，为 Agent 提供相应能力。 安装 Ollama 后，你可以使用以下命令下载并运行模型（模型大小约为 2GB，请确保磁盘空间充足）：

1. 运行 Llama 3.2 模型：

   ollama run llama3.2
   

2. 在仓库根目录中，进入 samples 目录，然后运行以下命令，部署使用 Currency Exchange MCP Server 的 Currency Exchange A2A Agent：

   cd samples && docker compose up -d
   

3. [可选] 使用提供的测试客户端测试示例。

第 2 步：使用 CLI 创建本地保险库并生成密钥

1. 创建本地保险库以存储生成的加密密钥：

   identity vault connect file -f ~/.identity/vault.json -v "My Vault"
   

2. 生成新的密钥对并将其存储在保险库中：

   identity vault key generate
   

第 3 步：注册为发行方

在此演示中，我们将使用 Okta 作为 IdP，为发行方创建应用程序。 为了快速创建试用帐户和应用程序，我们提供了一个脚本，可通过 Okta CLI 自动完成此流程。

重要

如果你已有 Okta 帐户，可以使用 okta login 命令登录现有组织。

如果注册新的 Okta 开发者帐户失败，请手动注册试用帐户，然后按照 Okta CLI 的说明使用 okta login 命令。

1. 在仓库根目录中运行以下命令，创建新的 Okta 应用程序：

   . ./demo/scripts/create_okta_app
   

2. 在交互式提示中，选择以下选项：

   > 4: Service (Machine-to-Machine), > 5: Other

3. 使用 Issuer CLI 和上一步中的环境变量注册发行方：

   identity issuer register -o "My Organization" \
       -c "$OKTA_OAUTH2_CLIENT_ID" -s "$OKTA_OAUTH2_CLIENT_SECRET" -u "$OKTA_OAUTH2_ISSUER"
   

说明

现在，你可以通过 http://localhost:4000/v1alpha1/issuer/{common_name}/.well-known/jwks.json访问 Issuer's Well-Known Public Key， 其中 {common_name} 是你注册时提供的通用名称。

步骤 4：为 MCP 服务生成元数据

使用 Okta 为 MCP 服务元数据创建第二个应用，方法与上一步类似：

1. 在仓库根目录运行以下命令，创建新的 Okta 应用：

   . ./demo/scripts/create_okta_app
   

2. 在交互式提示中，选择以下选项：

   > 4: Service (Machine-to-Machine)、> 5: Other

3. 使用 Issuer CLI 和上一步中的环境变量为 MCP 服务生成元数据：

   identity metadata generate -c "$OKTA_OAUTH2_CLIENT_ID" \
       -s "$OKTA_OAUTH2_CLIENT_SECRET" -u "$OKTA_OAUTH2_ISSUER"
   

说明

成功执行后，此命令会打印元数据 ID。你需要在下一步中使用该 ID 查看与此元数据关联的已发布徽章。

步骤 5：为 MCP 服务颁发并发布徽章

1. 为 MCP 服务颁发徽章：

   identity badge issue mcp -u http://localhost:9090 -n "My MCP Server"
   

2. 发布徽章：

   identity badge publish
   

说明

现在，你可以通过 http://localhost:4000/v1alpha1/vc/{metadata_id}/.well-known/vcs.json 访问 VCs as a Well-Known， 其中 {metadata_id} 是你在上一步生成的元数据 ID。

（可选）步骤 6：验证已发布的徽章

你可以使用 Issuer CLI 验证任何已发布的徽章，不仅限于你自己颁发的徽章。 这样，其他人也可以验证你发布的 Agent 和 MCP 徽章。

1. 下载你在上一步创建的徽章，将 {metadata_id} 替换为步骤 4 中的元数据 ID：

   curl -o vcs.json http://localhost:4000/v1alpha1/vc/{metadata_id}/.well-known/vcs.json
   

2. 使用 Issuer CLI 验证徽章：

   identity verify -f vcs.json
   

说明

你也可以使用我们的 Python SDK 以编程方式验证徽章。详情请参阅 Python SDK。

开发

如需更详细的开发说明，请参阅以下章节：

• Node 后端
• Issuer CLI
• 示例
• API 规范
• Node 客户端 SDK

路线图

请参阅未解决的问题，了解 计划添加的功能（以及已知问题）。

贡献

贡献让开源社区成为一个如此适合学习、启发和创造的地方。我们非常感谢 你做出的任何贡献。有关详细的贡献指南，请参阅 CONTRIBUTING.md。

版权声明

版权声明和许可证

根据 Apache 2.0 许可证分发。详情请参阅 LICENSE。 版权所有 AGNTCY 贡献者。