文档中心

AgentKit

凭据管理

创建第三方 API Key 凭据

API Key 凭据主要用于托管各类第三方服务颁发的固定访问密钥。凭据创建完成后，Agent 业务代码仅需通过预设的凭据名称即可引用对应的密钥配置；平台会在发起出站外部请求时，自动完成密钥注入。该方案能够有效规避在业务代码、容器镜像、本地配置文件中硬编码密钥等敏感信息带来的安全风险。

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

适用场景

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

当 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 绑定。

操作步骤

步骤一：选择凭据类型

登录AgentKit控制台。

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

单击“新建凭据”按钮，并在“选类型”页面选择“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、访问日志或浏览器历史记录中，建议优先使用。 Query：将 API Key 作为 URL 查询参数发送，例如 https://api.example.com?key=xx。注意仅第三方目标服务明确要求时使用，并注意避免 URL 被日志、监控系统或浏览器历史记录保存而导致密钥泄露。
资源管理
所属项目	该凭据所属项目，系统默认选择default（默认项目）；也可按需切换项目或新建项目。项目是一组资源的集合。支持将当前创建的凭据添加至指定项目，并按项目维度统一管理，以实现资源隔离与数据安全管控。项目更多信息请参见项目管理。一个资源仅可归属于一个项目，如需更改凭据所属项目，可单击所属项目下拉列表并选择目标项目。选定项目后，创建的凭据仅支持具有该项目权限的用户访问和使用。如当前项目不符合业务需求，可单击“新建项目”按钮进行创建。创建完成后，返回当前页面并选择新建的项目。

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

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

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

说明

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

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

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

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

步骤四：确认创建结果

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

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

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

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

常见问题

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

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

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

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

什么情况下需要设置 API Key 传递方式？

当目标服务要求使用特定 Header、查询参数或自定义字段传递 API Key 时配置；若目标服务与默认注入方式兼容，可保持未勾选。

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

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

最近更新时间：2026.10.12 17:21:40

这个页面对您有帮助吗？

有用

无用