命名空间：microsoft.graph
重要
Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。
更新 agentInstance 对象的属性。 还可以通过在请求正文中包含 清单来更新与代理实例关联的 agentCardManifest 。
此 API 可用于以下国家级云部署。
| 全局服务 | 美国政府 L4 | 美国政府 L5 (DOD) | 由世纪互联运营的中国 |
|---|---|---|---|
| ✅ | ❌ | ❌ | ❌ |
权限
为此 API 选择标记为最低特权的权限。 只有在应用需要它时，才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。
| 权限类型 | 最低特权权限 | 更高特权权限 |
|---|---|---|
| 委派（工作或学校帐户） | AgentInstance.ReadWrite.All | 不可用。 |
| 委派（个人 Microsoft 帐户） | 不支持。 | 不支持。 |
| 应用程序 | AgentInstance.ReadWrite.All | AgentInstance.ReadWrite.ManagedBy |
重要
使用委托权限时，必须为经过身份验证的用户分配受支持的Microsoft Entra角色或具有支持的角色权限的自定义角色。 代理注册表管理员 是此作支持的最低特权角色。
HTTP 请求
PATCH /agentRegistry/agentInstances/{agentInstanceId}
请求标头
| 名称 | 说明 |
|---|---|
| Authorization | 持有者 {token}。 必填。 详细了解 身份验证和授权。 |
| Content-Type | application/json. 必需。 |
请求正文
在请求正文中， 仅 提供要更新的属性的值。 请求正文中未包含的现有属性会保留其以前的值，或者根据对其他属性值的更改重新计算。
下表指定可更新的属性。
| 属性 | 类型 | 说明 |
|---|---|---|
| ownerIds | 字符串集合 | 代理实例的所有者标识符列表，可以是用户或服务主体。 必填。 |
| managedBy | String | 管理此代理的应用程序标识符。 可选。 |
| originatingStore | String | 代理源自的存储/系统的名称。 可选。 |
| createdBy | String | 创建代理实例的用户 (只读) 。 可选。 |
| displayName | String | 代理实例的显示名称。 必填。 |
| sourceAgentId | String | 来自源系统的原始代理标识符。 可选。 |
| agentIdentityBlueprintId | String | 代理标识蓝图标识符。 可选。 |
| agentIdentityId | String | Entra 代理标识标识符。 可选。 |
| agentUserId | String | 与代理关联的用户标识符。 可选。 |
| createdDateTime | DateTimeOffset | (只读) 创建代理实例时的时间戳。 可选。 |
| lastModifiedDateTime | DateTimeOffset | 上次修改的时间戳 (只读) 。 可选。 |
| url | String | 代理实例的终结点 URL。 可选。 |
| preferredTransport | String | 首选传输协议 (JSONRPC、GRPC、HTTP+JSON) 。 可选。 |
| additionalInterfaces | agentInterface 集合 | 代理支持的其他接口/传输 (url、传输) 。 可选。 |
| 签名 | agentCardSignature 集合 | 代理实例的数字签名 (受保护、签名、标头) 。 可选。 |
响应
如果成功，此方法在响应正文中返回响应 200 OK 代码和更新的 agentInstance 对象。
示例
示例 1：更新 agentInstance 中的 agentCardManifest
请求
以下示例显示了一个请求。 如果 agentCardManifest 尚不存在，则请求还会创建该代理。
PATCH https://graph.microsoft.com/beta/agentRegistry/agentInstances/{agentInstanceId}
Content-Type: application/json
{
"agentCardManifest": {
"ownerIds": [
"0ef68a76-e247-41dd-947b-41282760a2ac"
],
"originatingStore": "Copilot Studio",
"displayName": "Conditional Access Agent Card",
"description": "Manages organizational conditional access policies",
"iconUrl": "https://example.com/icon.png",
"provider": {
"organization": "Test Organization",
"url": "https://test.com"
},
"protocolVersion": "1.0",
"version": "1.0.0",
"documentationUrl": "https://example.com/docs",
"capabilities": {
"streaming": false,
"pushNotifications": false,
"stateTransitionHistory": true,
"extensions": [
{
"uri": "https://contoso.example.com/a2a/capabilities/secureMessaging",
"description": null,
"required": false,
"params": {
"useHttps": true
}
}
]
},
"defaultInputModes": [
"application/json"
],
"defaultOutputModes": [
"application/json",
"text/html"
],
"supportsAuthenticatedExtendedCard": true,
"skills": [
{
"id": "threat-detection",
"displayName": "Threat Detection",
"description": "Detect security threats in real-time",
"tags": [
"security",
"threat",
"detection"
],
"examples": [
"Analyze this log for threats",
"Check for malware"
],
"inputModes": [
"application/json",
"text/plain"
],
"outputModes": [
"application/json",
"text/html"
]
}
]
}
}
响应
以下示例显示了相应的响应。
HTTP/1.1 204 No Content
示例 2：更新 agentInstance 以引用现有 agentCardManifest
请求
以下示例显示了一个请求。
PATCH https://graph.microsoft.com/beta/agentRegistry/agentInstances/{agentInstanceId}
Content-Type: application/json
{
"agentCardManifest@odata.bind": "https://graph.microsoft.com/beta/agentRegistry/agentCardManifests('employee-assistant')"
}
响应
以下示例显示了相应的响应。
HTTP/1.1 204 No Content
示例 3：更新 displayName
请求
以下示例显示了一个请求。
PATCH https://graph.microsoft.com/beta/agentRegistry/agentInstances/{agentInstanceId}
Content-Type: application/json
{
"displayName": "Teams Meeting Scheduler Agent"
}
响应
以下示例显示了相应的响应。
HTTP/1.1 204 No Content