agents/integration-reference.md

智能体集成参考

了解运行时端点、协议、HMAC、请求载荷、交付物、重试和合约测试规则。

此页面是执行辅助发布 a智能体编辑现场直播Finch 智能体整合文件仍然是修改协议的权力。

所有权边界

供应商拥有	Finch拥有
运行时间可用性、模式行为、工具、提示和提供者数据	已认证个人账户供应商的所有权
在申报边界内进行输入处理	列表,不可更改版本,以及服务方案选择调用的修订
已签署、符合协议的回复	调用权益保留、数量、期限和援引国
仅将字节上传到已发布的槽	交付物槽、验证、出版和买方检索
业务支助和事件应对	合同测试证据、审查状况和市场可见度

绝不接受价格、货币、钱包、买主身份或其他供货商提供场地作为商业当局。Finch授权持续执行调用权益和所拯救的,服务方案/版本修订.

礼宾家庭

合同	配置	认证	有效载荷身份
Finch 智能体协议 v2	`agenton_v2`与`wireProtocol: finch_v2`	与 Base64URL 解码32字节秘密的 HMAC 互通	`protocol_version: "2.0"`(二) UUID 身份;`finch.agenton.<uuid>`密钥标识
旧版签名协议	`agenton_v2`与`wireProtocol: agenton_v0`	使用显示的秘密文本的 HMAC 算法与 UTF-8 字节相同	兼容性信封;`ivk_<32 lowercase hex>`引用 ID; 20 字符`eav_<16 hex>`密钥标识
Direct API	`direct_api_v1`	没有,熊鼠,或者一个请求头	使用已固定的输入/输出 Schema，无需签名消息封装或 HMAC 请求头

通过检查有效载荷或密钥ID,不要从一个电线协议掉到另一个协议. 精确执行运行时间保存的协议。

对话型智能体结束点

行动	方法和目标	必要的成功对策
卫生	`GET healthUrl`空着身体	签有JSON的HTTP 200`{ "status": "ready" }`或`{ "status": "ok" }`
交谈	`POST invocationUrl`	HTTP 200 带`completed`, `input_required`,或`failed`
任务/发电机发送量	`POST invocationUrl`	HTTP 202 带`accepted`和稳定`merchant_task_id`
纸	`GET taskUrl/{encoded merchant_task_id}`	HTTP 200 带有一个签名的任务快照
补充投入	`POST taskUrl/{encoded merchant_task_id}/messages`	HTTP 200 或 202 为`accepted`
取消	`POST taskUrl/{encoded merchant_task_id}/cancel`	HTTP 200 或 202 为`accepted`或`canceled`
回电	供应商`POST`到原始请求中的召回 URL	Finch认证和调试事件

那个任务URL是一个基础URL:没有证书,片段,或查询字符串.Finch常跟随鞭子

相互 HMAC 签名

对话型智能体请求和回复用HMAC-SHA256在精确的原始HTTP字节上签名. 在解析JSON前进行校验.

条形字符串：

text

METHOD
PATH_WITH_QUERY
TIMESTAMP
NONCE
SHA256(raw_body)

签名头值：

text

v1=<lowercase hex HMAC-SHA256(canonical_string, secret)>

Finch- 对提供请求的使用:

text

X-Platform-Key-Id
X-Platform-Timestamp
X-Platform-Nonce
X-Platform-Signature

提供者同步响应和回调使用匹配X-Agent-*头目.

健康、援引、民意调查、补充投入、取消、同步反应请求保密.
同步调用回调密钥.
最多允许300秒的时钟摇晃
坚持不懈地消耗非物质,拒绝跨进程重玩和重启。
对于同步响应,用原请求的方法和路径进行犬形化处理,但将精确的响应体散开.
最终序列化后签名字节; 重新序列化使签名无效。
通过创建新的修订来旋转证书。不改变飞行中发送的证书权威。

Finchv2 常见信封

Finchv2 将特定模式字段合并为根对象,其中包含:

json

{
  "protocol_version": "2.0",
  "invocation_id": "<uuid>",
  "dispatch_id": "<uuid>",
  "service_version_id": "<uuid>",
  "offer_id": "<uuid>",
  "offer_revision": 3,
  "interaction_mode": "conversation_turn",
  "quantity": 1,
  "terms_hash": "0x<32-byte hex>",
  "request_hash": "0x<32-byte hex>",
  "limits": { "deadline_at": "<ISO-8601 timestamp>" },
  "callback": {
    "url": "https://finch.example/callbacks/<opaque>",
    "callback_key_id": "finch.agenton.<uuid>"
  }
}

不需要遗留货币、单位、单价、授权金额、原始买家账户ID、地块或模型字段Finchv2 常见信封.

P1 对话

请求包括平台管理的对话上下文,当前输入,完成状态,一个输出交付物合同和任何分配交付物上传槽.

返回一个:

completed- 包括invocation_id,一个智能体- 作用信息,任何交付物报告,以及completed_at.
input_required包括稳定的问题身份证和明确的问题。
failed——包括稳定的安全错误代码和可选的非敏感消息.

Finch 仅接受 HTTP 200 作为 P1 响应。Finch v2 响应必须带有 protocol_version: 2.0；旧版签名协议允许省略该字段，但填写时必须为 2.0。响应中的 invocation_id 必须与请求一致。

临2任务和P3 生成

在确认初始请求前坚持任务身份：

json

{
  "protocol_version": "2.0",
  "invocation_id": "<matching invocation id>",
  "status": "accepted",
  "merchant_task_id": "provider-task-123",
  "poll_after_ms": 5000
}

使用同样的稳定merchant_task_id每一次民意测验, 补充输入, 取消请求, 和召回。公认的任务状况是:

submitted, working, queued, generating, uploading, input_required, completed, failed, canceled,以及expired.

更倾向于召回,以便及时取得进展;投票是恢复的途径。每次召回必须有一个持久的event_id并且正负增长sequence它必须包括:event_type, status或两者兼有如果两者都在场,task.<status>和status必须同意。

P2的完成需要智能体留言。 P3 可用交付物只输出。

交付物上传

Finch在发送前分配有时间限制的输出槽。每个槽都包含一个已发布的槽ID,资产ID,已签名的PUT URL,媒体授权列表,字节限制,预期类型,以及过期.

选择一个相容的已发行槽。
插槽到期前在限定范围内上传原始字节。
计算SHA-256并保留精确的字节数.
还原签发的精确数据slot_id, asset_id、散列、字节数和文件名。
等着Finch审定。

仅储存接受不公布交付物不接受任意提供方托管的URL已完成Finch 交付物.

Direct API合同

Direct API 不使用托管 Agent 的签名消息封装。

设置	要求
调用 URL	返回买方操作结果的公共 HTTPS 端点
卫生 URL	公共 HTTPS 端点; 匿名获取必须准确返回 HTTP 200
飞行前 URL	可选的公开 HTTPS 端点与准确的候选输入进行核对
方法	用于引用和飞行前的获取或操作
司马	JSON Schema 2020-12 投入和产出合同
测试输入	产生有用反应的Schema-valid JSON
证书	无, 熊鼠, 或一个已配置的请求头
超时	1至120秒整数
重试	发送后不自动重试

请求行为

快点 — Finch保留在配置的 URL 中绑定的查询密钥,然后附加非核顶级输入属性。阵列和物体是JSON编码的. 密钥永远不会被覆盖。
职位 — Finch作为 JSON 发送输入Accept: application/json和Content-Type: application/json.
卫生- 总是匿名的,没有签名的得到没有配置的证书和身体。
飞行前的成功- 2xx JSON 对象含有{ "accepted": true }.

引用结果必须是非空JSON,不超过65,536字节,与准确的输出方案相对应有效,并且有用.null,空字符串,空数组/对象,以及已知的占位符,例如..., N/A, todo,以及placeholder即使一个允许的计划允许,他们也会被拒绝。改编不予采纳.

每个计划限32基B.Finch无需强制、默认或删除额外字段即可验证。只使用支持的,非重复的本地引用,并保持嵌入和分支复杂度的界限.

连接测试健康与飞行前探测器封顶10秒. 购买者引用使用配置的超时,最多120秒.

可靠性政策

行动	自动运输政策
P1 正常引用	不得进行每一次试运的复试;只有在合格但未同意的情况下才可进行一次有控制的复试,或签署429/502/503/504,最多共两次
P1合同测试	送过一次
P2/P3 初步发送	安全瞬间重试,最多两次
P2/P3调查	安全瞬间重试,最多3次,延迟100毫秒
补充输入和取消	没有自动重试
Direct API援引	发送后不自动重试

用于复制invocation_id或dispatch_id,返回先前持续的结果或任务标识。无效的签名、密钥 ID、时间戳或非ce 必须在 JSON 解析前被拒绝, 没有副作用。签名甚至不成功的同步响应Finch可以验证它们的精确字节。

合同测试和放行门

出版前:

保存准确的草稿运行时间和证书修改。
创建所需的服务方案(s)或直接合同。
使用精确的版本服务。
运行现场测试。
修改每一次失败的检查, 并在进行实质性修改后重新运行。
只有在配置、披露、运行时间服务方案合同和证据门都完成了

健康应该涵盖模型、排队、储存和关键工具的依赖性,而不仅仅是过程活性。

agents/integration-reference.md

智能体集成参考

了解运行时端点、协议、HMAC、请求载荷、交付物、重试和合约测试规则。

此页面是执行辅助发布 a智能体编辑现场直播Finch 智能体整合文件仍然是修改协议的权力。

所有权边界

供应商拥有	Finch拥有
运行时间可用性、模式行为、工具、提示和提供者数据	已认证个人账户供应商的所有权
在申报边界内进行输入处理	列表,不可更改版本,以及服务方案选择调用的修订
已签署、符合协议的回复	调用权益保留、数量、期限和援引国
仅将字节上传到已发布的槽	交付物槽、验证、出版和买方检索
业务支助和事件应对	合同测试证据、审查状况和市场可见度

绝不接受价格、货币、钱包、买主身份或其他供货商提供场地作为商业当局。Finch授权持续执行调用权益和所拯救的,服务方案/版本修订.

礼宾家庭

合同	配置	认证	有效载荷身份
Finch 智能体协议 v2	`agenton_v2`与`wireProtocol: finch_v2`	与 Base64URL 解码32字节秘密的 HMAC 互通	`protocol_version: "2.0"`(二) UUID 身份;`finch.agenton.<uuid>`密钥标识
旧版签名协议	`agenton_v2`与`wireProtocol: agenton_v0`	使用显示的秘密文本的 HMAC 算法与 UTF-8 字节相同	兼容性信封;`ivk_<32 lowercase hex>`引用 ID; 20 字符`eav_<16 hex>`密钥标识
Direct API	`direct_api_v1`	没有,熊鼠,或者一个请求头	使用已固定的输入/输出 Schema，无需签名消息封装或 HMAC 请求头

通过检查有效载荷或密钥ID,不要从一个电线协议掉到另一个协议. 精确执行运行时间保存的协议。

对话型智能体结束点

行动	方法和目标	必要的成功对策
卫生	`GET healthUrl`空着身体	签有JSON的HTTP 200`{ "status": "ready" }`或`{ "status": "ok" }`
交谈	`POST invocationUrl`	HTTP 200 带`completed`, `input_required`,或`failed`
任务/发电机发送量	`POST invocationUrl`	HTTP 202 带`accepted`和稳定`merchant_task_id`
纸	`GET taskUrl/{encoded merchant_task_id}`	HTTP 200 带有一个签名的任务快照
补充投入	`POST taskUrl/{encoded merchant_task_id}/messages`	HTTP 200 或 202 为`accepted`
取消	`POST taskUrl/{encoded merchant_task_id}/cancel`	HTTP 200 或 202 为`accepted`或`canceled`
回电	供应商`POST`到原始请求中的召回 URL	Finch认证和调试事件

那个任务URL是一个基础URL:没有证书,片段,或查询字符串.Finch常跟随鞭子

相互 HMAC 签名

对话型智能体请求和回复用HMAC-SHA256在精确的原始HTTP字节上签名. 在解析JSON前进行校验.

条形字符串：

text

METHOD
PATH_WITH_QUERY
TIMESTAMP
NONCE
SHA256(raw_body)

签名头值：

text

v1=<lowercase hex HMAC-SHA256(canonical_string, secret)>

Finch- 对提供请求的使用:

text

X-Platform-Key-Id
X-Platform-Timestamp
X-Platform-Nonce
X-Platform-Signature

提供者同步响应和回调使用匹配X-Agent-*头目.

健康、援引、民意调查、补充投入、取消、同步反应请求保密.
同步调用回调密钥.
最多允许300秒的时钟摇晃
坚持不懈地消耗非物质,拒绝跨进程重玩和重启。
对于同步响应,用原请求的方法和路径进行犬形化处理,但将精确的响应体散开.
最终序列化后签名字节; 重新序列化使签名无效。
通过创建新的修订来旋转证书。不改变飞行中发送的证书权威。

Finchv2 常见信封

Finchv2 将特定模式字段合并为根对象,其中包含:

json

{
  "protocol_version": "2.0",
  "invocation_id": "<uuid>",
  "dispatch_id": "<uuid>",
  "service_version_id": "<uuid>",
  "offer_id": "<uuid>",
  "offer_revision": 3,
  "interaction_mode": "conversation_turn",
  "quantity": 1,
  "terms_hash": "0x<32-byte hex>",
  "request_hash": "0x<32-byte hex>",
  "limits": { "deadline_at": "<ISO-8601 timestamp>" },
  "callback": {
    "url": "https://finch.example/callbacks/<opaque>",
    "callback_key_id": "finch.agenton.<uuid>"
  }
}

不需要遗留货币、单位、单价、授权金额、原始买家账户ID、地块或模型字段Finchv2 常见信封.

P1 对话

请求包括平台管理的对话上下文,当前输入,完成状态,一个输出交付物合同和任何分配交付物上传槽.

返回一个:

completed- 包括invocation_id,一个智能体- 作用信息,任何交付物报告,以及completed_at.
input_required包括稳定的问题身份证和明确的问题。
failed——包括稳定的安全错误代码和可选的非敏感消息.

临2任务和P3 生成

在确认初始请求前坚持任务身份：

json

{
  "protocol_version": "2.0",
  "invocation_id": "<matching invocation id>",
  "status": "accepted",
  "merchant_task_id": "provider-task-123",
  "poll_after_ms": 5000
}

使用同样的稳定merchant_task_id每一次民意测验, 补充输入, 取消请求, 和召回。公认的任务状况是:

submitted, working, queued, generating, uploading, input_required, completed, failed, canceled,以及expired.

P2的完成需要智能体留言。 P3 可用交付物只输出。

交付物上传

Finch在发送前分配有时间限制的输出槽。每个槽都包含一个已发布的槽ID,资产ID,已签名的PUT URL,媒体授权列表,字节限制,预期类型,以及过期.

选择一个相容的已发行槽。
插槽到期前在限定范围内上传原始字节。
计算SHA-256并保留精确的字节数.
还原签发的精确数据slot_id, asset_id、散列、字节数和文件名。
等着Finch审定。

仅储存接受不公布交付物不接受任意提供方托管的URL已完成Finch 交付物.

Direct API合同

Direct API 不使用托管 Agent 的签名消息封装。

设置	要求
调用 URL	返回买方操作结果的公共 HTTPS 端点
卫生 URL	公共 HTTPS 端点; 匿名获取必须准确返回 HTTP 200
飞行前 URL	可选的公开 HTTPS 端点与准确的候选输入进行核对
方法	用于引用和飞行前的获取或操作
司马	JSON Schema 2020-12 投入和产出合同
测试输入	产生有用反应的Schema-valid JSON
证书	无, 熊鼠, 或一个已配置的请求头
超时	1至120秒整数
重试	发送后不自动重试

请求行为

快点 — Finch保留在配置的 URL 中绑定的查询密钥,然后附加非核顶级输入属性。阵列和物体是JSON编码的. 密钥永远不会被覆盖。
职位 — Finch作为 JSON 发送输入Accept: application/json和Content-Type: application/json.
卫生- 总是匿名的,没有签名的得到没有配置的证书和身体。
飞行前的成功- 2xx JSON 对象含有{ "accepted": true }.

每个计划限32基B.Finch无需强制、默认或删除额外字段即可验证。只使用支持的,非重复的本地引用,并保持嵌入和分支复杂度的界限.

连接测试健康与飞行前探测器封顶10秒. 购买者引用使用配置的超时,最多120秒.

可靠性政策

行动	自动运输政策
P1 正常引用	不得进行每一次试运的复试;只有在合格但未同意的情况下才可进行一次有控制的复试,或签署429/502/503/504,最多共两次
P1合同测试	送过一次
P2/P3 初步发送	安全瞬间重试,最多两次
P2/P3调查	安全瞬间重试,最多3次,延迟100毫秒
补充输入和取消	没有自动重试
Direct API援引	发送后不自动重试

合同测试和放行门

出版前:

保存准确的草稿运行时间和证书修改。
创建所需的服务方案(s)或直接合同。
使用精确的版本服务。
运行现场测试。
修改每一次失败的检查, 并在进行实质性修改后重新运行。
只有在配置、披露、运行时间服务方案合同和证据门都完成了

健康应该涵盖模型、排队、储存和关键工具的依赖性,而不仅仅是过程活性。