文档中心

AgentKit

凭据管理

创建第三方 API Key 凭据

API Key 凭据用于托管第三方服务颁发的固定访问密钥，避免将密钥硬编码到业务代码、容器镜像或本地配置文件中。

本文介绍如何在 AgentKit 控制台中创建 API Key 类型的凭据，完成凭据名称、API Key 值、密钥存储方式、加密方式等配置，使 Agent 能够安全地使用该凭据访问第三方服务。

说明

在控制台创建凭据后，普通 HTTP 请求不会自动携带 API Key。使用凭据前，还需要完成出站代理或 SDK 接入，并配置凭据与 Agent 的绑定关系及取用权限。

出站代理接入：适用于通过 MCP 服务、网关或统一代理访问下游 API 的场景。了解更多

SDK 或接口接入:适用于 Agent 业务代码直接调用第三方 API 的场景。了解更多

适用场景

访问使用固定密钥认证的外部服务

当 Agent 需要调用使用固定 API Key 进行身份认证的第三方模型、搜索服务、数据库服务或业务 API 时，可以创建 API Key 凭据。平台会在 Agent 发起出站请求时按配置注入密钥，使 Agent 能够完成目标服务认证。

避免在代码中明文维护密钥

若不希望在 Agent 代码、代码仓库、镜像、配置文件或运行参数中保存 API Key 明文，可通过 API Key 凭据将密钥与业务代码解耦，避免敏感信息随代码流转或被误提交。

统一存储和加密管理凭据

当业务对密钥安全、审计或生命周期管理有要求时，可通过 KMS 主密钥对凭据进行加密，或使用凭据托管服务统一存储和管理凭据。以此降低密钥泄露风险，并便于后续进行凭据更新、轮换。

按项目和 Agent 控制使用范围

当同一凭据需要按业务项目、环境或资源归属进行管理时，可为凭据配置所属项目。同时，可将凭据绑定到指定 Agent，限定引用该凭据的 Agent，避免凭据被不相关的 Agent 使用。

前提条件

获取有效的 API Key

已从目标服务提供方获取可用的 API Key，并确认该密钥具备 Agent 调用目标服务所需的权限。建议同时确认密钥的适用环境、有效期、调用额度、访问范围及是否存在 IP 白名单等限制，避免创建完成后因密钥权限不足或环境不匹配导致调用失败。

准备 KMS 密钥资源（可选）

若在创建凭据时选择使用“自定义主密钥”进行加密，请先在 KMS 中创建可用的密钥环和主密钥，并确认当前账号具备使用该主密钥加密和解密凭据的权限。详情请参见密钥管理快速入门。

说明

若暂无需自主管理密钥，可选择系统默认密钥，由平台托管加密配置，以减少额外准备工作。

创建目标 Agent（可选）

若希望在创建凭据过程中立即完成绑定，请提前创建需要使用该凭据的目标 Agent。绑定后，目标 Agent 才能在运行时引用该凭据完成出站调用。

说明

若暂时不确定需要绑定的 Agent，也可以先完成凭据创建后再进行 Agent 绑定。

操作步骤

步骤一：选择凭据类型

在左侧导航树，选择“身份与权限 > 凭据管理”。

单击“新建凭据”按钮，并在“选类型”页面选择“API Key”。

单击“下一步”按钮。

步骤二：配置凭据参数

参考下表，完成凭据参数配置。

配置项	说明
基础信息
API Key 名称	自定义输入凭据的名称，建议名称能够区分提供方、用途和环境。
API Key 值	填入您从第三方服务获取的实际密钥值。注意请勿在工单、聊天消息、运行日志、截图、代码仓库、配置文件或公开文档等中记录、粘贴或展示完整的 API Key，避免密钥在协作、排障或代码流转过程中意外泄露。
智能体身份池（可选）	指当前账户下用于管理智能体身份的资源池，可用于隔离不同业务或环境中的 API Key 凭据。 AgentKit 默认提供名为 default 的智能体身份池，若无业务隔离、环境隔离或独立权限管理要求，可直接使用该默认身份池。若需按业务、团队或环境单独管理凭据，请完成对应智能体身份池创建后，在当前页面选择新建的身份池。
加密方式	根据凭据管理要求选择指定 API Key 的安全存储方式。支持以下选项： KMS 加密（平台存储）凭据写入时，系统使用所选 KMS 主密钥进行加密，并仅以密文形式存储在平台中。适用于需要通过系统默认密钥或自定义主密钥保护凭据的场景。凭据托管（托管存储）凭据交由凭据托管服务统一存储和管理，适用于需要集中管理凭据及其生命周期的场景。
主密钥来源	当加密方式选择为KMS 加密（平台存储）时，需要配置主密钥来源。系统默认密钥由平台托管，开箱即用，无需额外配置，适合快速接入和常规使用场景。自定义主密钥使用自有 KMS 主密钥加密凭据。选择后，依次选择“KMS 密钥环”和“KMS 主密钥”。适用于有独立密钥管理、审计或合规要求的场景。说明 KMS 密钥环和KMS 主密钥获取方式请参见前提条件。使用自定义 KMS 主密钥时，避免随意禁用、删除或调整密钥权限，以免影响凭据解密和 Agent 调用。
设置 API Key 传递方式（可选）	指定 Agent 发起 API 请求时注入 API Key 的位置。请根据目标服务的认证要求选择： Header（推荐）将 API Key 作为 HTTP 请求头发送。相比 Query 方式，密钥不易出现在 URL、访问日志或浏览器历史记录中，建议优先使用。参数名称：填写查询参数名称（请求头名称），例如Authorization、X-API-Key。 Prefix 配置 API Key 之前需要添加的固定前缀。系统按照“Prefix + API Key”的方式拼接请求头值，不会自动补充空格，也不会对请求头中的空格进行 URL 编码。如果目标服务要求使用 Bearer 认证，请在 Prefix 中输入 Bearer ，其中 Bearer 后必须保留 1 个半角空格。为避免界面中末尾空格不易识别。配置示例：示例 1：带前缀参数名称：Authorization Prefix：Bearer（末尾含 1 个半角空格）最终请求头示例：Authorization: Bearer <API_KEY>。示例 2：不带前缀参数名称：X-API-Key Prefix：无最终请求头示例：X-API-Key: <API_KEY>。 Query 将 API Key 作为 URL 查询参数发送，即在请求 URL 后追加指定的查询参数，并将 API Key 作为参数值一并传递给目标服务。该方式通常用于部分历史接口、轻量级开放接口，或第三方服务明确要求通过 URL 参数进行身份校验的场景。注意仅当目标服务明确要求时，才建议使用 Query，并注意避免 URL 被日志、监控系统或浏览器历史记录保存而导致密钥泄露。参数名称：填写目标服务要求的查询参数名称，例如api_key、access_key、access_token。参数名称具体请以第三方接口文档或对接规范为准。 Prefix：可指定 API Key 的前缀，例如 Bearer 。如第三方要求在密钥前拼接固定标识，请按要求填写，并保留前缀末尾空格。实际发起请求时，前缀与 API Key 会拼接后作为参数值传递。配置示例示例 1：不带前缀参数名称：api_key Prefix：无最终请求 URL 示例：https://api.example.com/v1/resource?api_key=<API_KEY>。示例 2：带前缀参数名称：access_token Prefix：Bearer 最终请求 URL 示例：https://api.example.com/v1/resource?access_token=Bearer%20<API_KEY>。
资源管理
所属项目	用于设置凭据的资源归属。系统默认选择default（默认项目），也可以根据业务需要切换至其他项目或新建项目。所属项目用于管理凭据的资源归属和控制台管理权限，不直接作为 Agent 运行时取用凭据的授权判定依据。Agent 是否可以取用凭据，还需根据凭据与 Agent 的绑定关系、调用身份及相关权限配置进行判定。项目更多信息请参见项目管理。一个资源仅可归属于一个项目，创建凭据时，可以单击所属项目下拉列表并选择目标项目。凭据创建完成后，其控制台管理权限受所属项目的权限配置约束，只有具备相应项目权限的用户才能在控制台中查看或管理该凭据。如果现有项目不符合业务需求，可以单击新建项目。项目创建完成后，返回当前页面，刷新项目列表并选择新建的项目。

确认参数配置无误后，单击“创建并继续”按钮，进入绑定到 Agent 页面。

步骤三：绑定到 Agent（可选）

将凭据绑定到 Agent 后，目标 Agent 才能在运行时引用该凭据完成出站调用。为遵循最小授权原则，建议仅绑定确有调用需求的 Agent，避免扩大凭据的使用范围。

说明

如果暂时无法确定需要授权的 Agent，可以跳过本步骤，先完成凭据创建，后续再进入凭据详情页补充绑定。相关操作请参见绑定与解绑 Agent。

在 Agent 列表中选择需要使用该凭据的目标 Agent。

确认所选 Agent 无误后，单击“下一步”按钮。

如暂不绑定，可不选择任何 Agent，直接单击“下一步”按钮进入后续流程。

步骤四：确认创建结果

页面显示凭据创建成功，表示系统已完成凭据保存。结束创建流程前，请确认页面展示的凭据名称与预期一致，避免因名称填写错误而影响后续查找和使用。

确认凭据名称与本次创建的凭据一致。

如需核对凭据类型、所属项目、绑定资源或其他配置信息，单击“查看凭据详情”按钮，进入详情页进行检查。

确认无误后，单击“完成”按钮，结束创建流程。

常见问题

系统默认密钥和自定义主密钥如何选择？

若希望快速接入且无独立密钥管理要求，可选择系统默认密钥；若业务要求自主管理密钥、独立审计或满足特定合规要求，可选择自定义主密钥。

是否必须在创建过程中绑定 Agent？

不是。也可以凭据保存后可直接进入下一步，后续在凭据详情中完成绑定。

创建成功但调用仍然失败怎么办？

请检查密钥是否有效、Agent 是否已绑定、传递方式是否正确，以及 KMS 主密钥和身份池权限是否满足要求。必要时在目标服务侧查看认证失败信息。

凭据是否可以通过所属项目和智能体身份池来管理资源归属？

所属项目与智能体身份池属于凭据的归属、隔离标识信息，用于标记凭据所属业务范围，记录凭据的创建与使用上下文。

说明

所属项目和智能体身份池仅用于描述资源归属与隔离范围，不属于运行时授权判定依据。配置项目或身份池，不代表已自动完成统一授权，也不能仅凭这两个字段判断 Agent 运行时是否有权使用该凭据。Agent 运行时能否取用凭据，还需结合凭据状态、绑定关系及运行时取用授权等配置综合判断。

只要选择了所属项目或智能体身份池，就能判断 Agent 执行时一定能使用该凭据吗？

不能。所属项目和智能体身份池只能反映凭据的归属范围或隔离上下文，不能单独作为运行时可用性的判断依据。实际是否可用，还需结合凭据绑定关系、凭据状态、类型匹配及运行时授权配置综合判断。

凭据的管理权限，和 Agent 运行时取用凭据的权限，是同一类权限吗？

不是。二者分属不同层面的授权能力，相互独立，需要分开配置。

二者存在关联，但权限不可互相替代：拥有凭据管理权限，不代表对应的 Agent 运行时就能够取用凭据；反之，Agent 运行时可以取用凭据，也不代表操作者拥有该凭据的管理权限。

凭据管理权限

控制控制台侧的操作权限，定义谁能够查看、新建、编辑、删除与维护凭据资产，一般对应控制台管理面的 IAM 权限。

Agent 运行时取用凭据权限

控制运行时执行阶段的使用权限，定义指定 Agent 在执行任务、调用下游服务时，是否允许读取并使用该凭据。

最近更新时间：2026.10.29 17:04:11

这个页面对您有帮助吗？

有用

无用