跳转到主要内容
POST
更新 A2A 智能体

限制说明

使用说明

  • 需要对智能体当前所属团队有编辑权限:账户级智能体(team_id=0)仅账户 owner 或管理员可改;团队智能体仅该团队成员可改(owner/管理员也必须是该团队成员)。
  • 改到其他团队(team_id > 0)要求调用者属于目标团队;改为账户级(team_id=0)仅限账户 owner 或管理员。变更团队但未同时传 environments 时,现有 Runner 条目必须对调用者仍可选,否则更新被拒绝。
  • auth_config 整体替换:未传入的键会被删除。对 api_key、token、client_secret,回传详情接口返回的脱敏值会保留已存储的密钥,传空字符串则清除该密钥。
  • 传入 auth_mode 时,secret_schema 会被同一请求中的值覆盖(未传则置空)。auth_mode 或 card_url 实际发生变化时会清空 oauth_metadata,除非同时传入非空的 oauth_metadata;只传空的 oauth_metadata 不会改动已存储的值。
  • 修改 card_url 会重新执行创建时的智能体卡片兼容性检查;修改 agent_name 会重新校验命名规则。
  • 每次调用都会记录到账户审计日志。

授权

app_key
string
query
必填

在 Flashduty 控制台 我的 → APP Key 中创建的 APP Key。可通过 query 参数 app_key 或请求头 Fd-App-Key 传入。实际可访问范围是该 APP Key 的权限范围与创建者当前角色权限的交集,请妥善保管。

请求体

application/json

对 A2A 智能体执行部分更新。字段为 null 或省略时保持不变。

agent_id
string
必填

目标智能体 ID,取自 POST /safari/a2a-agent/list 返回的列表。

agent_name
string | null

新的显示名称,省略表示不变。规则同创建:不能含 @,不能是 general / explore,在作用域内唯一。

Maximum string length: 128
instructions
string | null

新的指令文档(约定同创建:可带 summary frontmatter,正文非空,最大 50 KiB)。省略则保持不变。已弃用的 description 字段仍可传入,若两者同时传入则必须一致。

Maximum string length: 51200
card_url
string | null

新的卡片 URL,省略表示不变。校验与兼容性检查同创建;实际变更时,若未传新的 oauth_metadata,会将其清空。

auth_type
enum<string> | null

新的认证方式,省略表示不变。

  • none:不发送凭据请求头。
  • api_key:把 auth_config.api_key 放进 auth_config.header 指定名称的请求头。
  • bearer:发送 Authorization: Bearer <auth_config.token>。
可用选项:
none,
api_key,
bearer
auth_config
object

整体替换认证配置;省略则保持不变。未包含在 map 中的键会被删除。敏感键回传掩码值时保留已存储的密钥,传空字符串则清除该密钥。

streaming
boolean | null

切换流式支持。省略则保持不变。

team_id
integer<int64> | null

重新分配团队范围,省略表示不变。改到团队需是该团队成员;改为账户级(0)仅限账户 owner 或管理员。若变更团队但同一请求未传 environments,现有 Runner 条目必须对调用者仍可选,否则更新被拒绝。

environments
string[] | null

该智能体可运行的执行环境:cloud 和/或 BYOC Runner 的环境 ID 列表。省略(null)表示保持不变;传入列表即整体设置——空列表表示清除限制、恢复为所有环境。

auth_mode
enum<string> | null

新的认证模式,省略表示不变。取值(凭据由谁提供):

  • shared(默认,空值等同):使用保存在智能体上的一份凭据(auth_type + auth_config),所有调用者共用。
  • per_user_secret:每位用户各自保存密钥,放在 secret_schema.header_name 指定的请求头中发送。
  • per_user_oauth:每位用户各自完成 OAuth 授权,首次使用时完成发现与客户端注册。

传入时,secret_schema 会被同一请求中的值覆盖。

可用选项:
shared,
per_user_secret,
per_user_oauth
secret_schema
string | null

新的 JSON 密钥 schema,例如 {"header_name":"X-Api-Key"}。仅在同时传入 auth_mode 时生效,单独传入会被忽略。

oauth_metadata
string | null

新的 JSON OAuth 元数据。非空值按原样保存。省略或为空时保留原值;若 auth_mode 或 card_url 发生变化,则清空。

allow_insecure_oauth_http
boolean | null

切换该智能体的非回环 HTTP OAuth 发现开关。省略则保持不变。

allow_insecure_tls_skip_verify
boolean | null

切换该智能体的 TLS 证书验证跳过开关。省略则保持不变。

响应

成功

所有 Flashduty 公开 API 共用的标准响应结构。成功时 data 为接口专属载荷且不含 error;失败时 error 存在而 data 缺失。request_id 始终存在,并会同步写入 Flashcat-Request-Id 响应头。

request_id
string
必填

本次请求的唯一 ID,与 Flashcat-Request-Id 响应头一致。反馈问题时请携带该 ID。

示例:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

error
object

响应结构中的错误 payload,仅在非 2xx 响应时出现。

data
null

成功时不返回该字段,响应体只有 request_id。