在 Microsoft Entra 代理注册表中注册代理可在整个组织中集中查看和管理。 它提供所有代理的统一视图，包括来自非Microsoft生成器平台和标识提供者的代理。 注册过程因代理的创建方式而异。
注册表为每个代理存储两种密钥类型的信息：
- 代理实例：有关执行和管理的操作细节。
- 代理卡片清单：用于协作的发现元数据。
了解此区别可确保准确注册。
Microsoft产品集成
如果代理是基于以下Microsoft产品之一构建的，则无需将代理注册到代理注册表。 基于这些产品构建的代理会自动集成到代理实例和代理卡清单中，并包含有关代理 ID 的信息。 目前，Microsoft与 Microsoft Entra 代理注册表集成的产品包括：
先决条件
Microsoft Entra 代理 ID 是 Microsoft Agent 365 的一部分。 这两者都可通过 Microsoft 365 中的 边境计划 获得。 若要访问这些功能，必须拥有 Microsoft 365 Copilot 的许可证，并为用户启用 Frontier。
按照 Frontier 入门指南 进行操作，或使用以下步骤检查是否已启用 Frontier：
- 以计费管理员身份登录到 Microsoft 365 管理中心。
- 浏览到 Copilot>设置>用户访问>Copilot Frontier 并确保为用户启用。 如果未看到这些选项，请联系管理员以检查Microsoft 365 Copilot 许可。
在向注册表注册代理之前，请确保满足以下要求：
- 代理注册表管理员角色
- 具有
https://graph.microsoft.com/.default作用域的有效 Microsoft Entra 访问令牌 - 仅限应用的权限或委派的权限
- 对于非 Microsoft 代理，您需要代理的操作端点和元数据信息。
代理实例和代理卡片
在注册表中注册代理涉及创建代理实例和代理卡。
- 代理实例是在注册表中的登记，其中包含操作详细信息，例如代理的终结点 URL、代理标识、源存储和所有者信息。
- 代理卡包含描述代理的功能、技能和其他发现相关信息的元数据。 如果没有代理卡，您的代理将无法被发现。
创建代理实例时，无需同时创建代理卡。 稍后可以使用代理实例 ID 创建代理卡。 代理卡只能通过代理实例创建。 代理实例可以共享代理卡。
自助注册
在上面未列出的Microsoft平台上创建的代理和非Microsoft平台需要使用 Microsoft Graph API 进行自助注册。 此过程涉及：
- 注册代理程序实例进行库存和运营管理。
- 注册代理卡清单规范，以促进发现和协作。
注册代理实例
代理的实例包含代理执行与管理所需的操作信息。
确保你拥有所需的权限：
- 对于委托流：
AgentInstance.ReadWrite.All - 对于仅限应用的流：
AgentInstance.ReadWrite.AllAgentInstance.ReadWrite.ManagedBy
- 对于委托流：
发出 POST 请求以注册代理。
POST /beta/agentRegistry/agentInstances
Authorization: Bearer {token}
Content-Type: application/json
{
"displayName": "My Agent Instance",
"ownerIds": [
"11112222-bbbb-3333-cccc-4444dddd5555"
],
"sourceAgentId": "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
"originatingStore": "Copilot Studio",
"agentIdentityBlueprintId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"agentIdentityId": "aaaabbbb-6666-cccc-7777-dddd8888eeee",
"agentUserId": "22cc22cc-dd33-ee44-ff55-66aa66aa66aa",
"url": "https://conditional-access-agent.example.com/a2a/v1",
"preferredTransport": "JSONRPC",
"additionalInterfaces": [
{
"url": "https://conditional-access-agent.example.com/a2a/v1",
"transport": "JSONRPC"
},
{
"url": "https://conditional-access-agent.example.com/a2a/grpc",
"transport": "GRPC"
},
{
"url": "https://conditional-access-agent.example.com/a2a/json",
"transport": "HTTP+JSON"
}
],
"signatures": [
{
"protected": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
"signature": "BB88CC99DD00EE11FF22AA33BB44CC55DD66EE77",
"header": {
"kidHint": "contoso-key-1",
"nonce": "mN7oP8qR9sT0uV1wX2-yZ3aB4dE="
}
}
]
}
响应包括具有时间戳的已创建代理实例，并确认成功注册。 代理程序的 sourceAgentId 连接到其原始的平台标识符，而 originatingStore 表示代理程序创建的平台。
注册代理凭证
代理卡清单提供发现元数据，使其他代理和应用程序能够查找代理并与之交互。 使用相同的身份验证令牌，使用以下 API 调用注册代理卡：
POST /beta/agentRegistry/agentInstances
Authorization: Bearer {token}
Content-Type: application/json
{
"displayName": "",
"ownerIds": [],
"sourceAgentId": "",
"originatingStore": "",
"url": "",
"preferredTransport": "",
"agentIdentityBlueprintId": "",
"agentIdentityId": "",
"agentUserId": "",
"additionalInterfaces": [],
"signatures": [],
"agentCardManifest": {
"ownerIds": [],
"originatingStore": "",
"displayName": "",
"description": "",
"iconUrl": "",
"provider": {},
"protocolVersion": "",
"version": "",
"documentationUrl": "",
"capabilities": {},
"securitySchemes": {
"apiKeyAuth": {},
"entraAuth": {}
},
"security": [],
"signatures": [],
"defaultInputModes": ["application/json"],
"defaultOutputModes": ["application/json", "text/html"],
"supportsAuthenticatedExtendedCard": true,
"skills": []
}
}
技能集定义了代理提供的特定功能，从而实现基于所需功能的精确识别。 能力对象指定您的代理支持的集成协议的技术特性。
处理注册响应
注册成功返回 HTTP 201，使用完整的代理信息（包括系统生成的时间戳）创建。 如果注册失败，响应将包含有助于解决问题的错误详细信息：
| 错误代码 | Description | 决议 |
|---|---|---|
ValidationError |
缺少或无效的必填字段 | 根据架构要求查看请求有效负载 |
Unauthorized |
身份验证令牌无效 | 刷新令牌和重试请求 |
AgentAlreadyExists |
代理ID已注册 | 使用不同的 ID 或更新现有代理 |
常见的验证错误包括缺少必需字段，例如代理实例的id和isBlocked，或代理卡的name和skills。
验证代理注册
注册后，确认代理在注册表中正确显示。 可以通过 Microsoft Entra Admin Center 或使用 Microsoft 图形 API 来验证注册。
- 导航到 代理身份
- 选择 “代理注册表”。 您的代理不会有代理 ID，但如果您在注册过程中提供了相关信息，则可以查看其关联的元数据。