跳转到主要内容
POST
创建 A2A 智能体

限制说明

使用说明

  • instructions 为必填:Markdown 文档,可带 summary frontmatter,正文不能为空,最多 51,200 字节。已弃用的 description 字段仍可传入,若与 instructions 同时传入,两者必须完全一致。
  • agent_name 不能包含 @,也不能是内置智能体保留的 general / explore,且在其作用域(账户级或单个团队)内必须唯一;违反时返回 InvalidParameter。
  • card_url 必须是带 host 的绝对 http/https URL。若该智能体有在线的执行环境,服务端会通过该环境拉取智能体卡片(card_url 不带路径时自动补 /.well-known/agent-card.json),卡片不是合法 JSON、或未声明协议绑定为 JSONRPC / HTTP+JSON 的 A2A 1.x 接口时拒绝;卡片不可达、返回非 2xx 或没有在线环境时不阻断调用。
  • auth_type=bearer 时以 Authorization: Bearer <token> 发送 auth_config.token;auth_type=api_key 时把 auth_config.api_key 放进 auth_config.header 指定名称的请求头;为 none 或空值时不发送共享凭据请求头。
  • environments 的每一项必须是 cloud,或某个账户级 BYOC Runner、调用者所属团队的 BYOC Runner 的环境 ID;重复项会被去除,空字符串会被拒绝。省略或为空表示所有环境。
  • 创建到团队(team_id > 0)要求调用者属于该团队;只有账户 owner 或管理员可以在账户级(team_id=0)创建。
  • 新建的智能体 status 为 enabled。
  • 每次调用都会记录到账户审计日志。

授权

app_key
string
query
必填

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

请求体

application/json

新建 A2A 智能体的注册参数。

agent_name
string
必填

智能体显示名称,会话中按此名称调用智能体。不能包含 @,不能是 general 或 explore,且在其作用域(账户级或单个团队)内唯一。

Maximum string length: 128
instructions
string
必填

远程智能体的自然语言指令:Markdown 文档,可带 summary frontmatter,正文非空,最大 50 KiB(51200 字节)。必填 —— 已弃用的 description 字段仍保留以兼容旧客户端,若两者同时传入则必须与 instructions 完全一致。

Maximum string length: 51200
card_url
string
必填

远程智能体卡片的 URL。必须是 host 非空的绝对 http 或 https URL;不带路径时解析为 /.well-known/agent-card.json。若有在线执行环境,会拉取卡片并要求其声明 A2A 1.x 的 JSONRPC 或 HTTP+JSON 接口。

auth_type
enum<string>

使用共享凭据访问远程智能体时的认证方式:

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

省略时存为空字符串,效果同 none。

可用选项:
none,
api_key,
bearer
auth_config
object

共享凭据键值:auth_type=api_key 时使用 header 和 api_key,auth_type=bearer 时使用 token。api_key、token、client_secret 的值加密存储,响应中脱敏。

streaming
boolean

远程智能体是否支持流式响应。

team_id
integer<int64>

团队范围:0 = 账户级;>0 = 团队。在账户级创建需要 owner/admin 角色;创建到某个团队需要真实属于该团队。

environments
string[]

该智能体可运行的执行环境:cloud 和/或 BYOC Runner 的环境 ID 列表。省略或为空表示所有环境。

auth_mode
enum<string>
默认值:shared

凭据由谁提供:

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

per_user_secret 要求 secret_schema 带非空的 header_name;其他取值返回 InvalidParameter。

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

JSON 编码的密钥 schema,例如 {"header_name":"X-Api-Key"};auth_mode=per_user_secret 时必填。

oauth_metadata
string

JSON 编码的 OAuth 元数据;由 per_user_oauth 模式的 OAuth 发现流程填充。

allow_insecure_oauth_http
boolean

允许该智能体使用非回环的 HTTP OAuth 发现/元数据端点,而非强制 HTTPS。默认为 false。

allow_insecure_tls_skip_verify
boolean

连接到该智能体端点时跳过 TLS 证书验证(自签/私有证书)。默认为 false。

响应

成功

所有 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
object

注册 A2A 智能体的结果。