refactor(agent-runner): remove protocol_version from various components and update related documentation

This commit is contained in:
huanghuoguoguo
2026-06-09 20:57:06 +08:00
parent f92029e245
commit 35661081ad
18 changed files with 36 additions and 122 deletions

View File

@@ -41,12 +41,12 @@ Agent / binding 的持久化形态。
外部 harness runnerClaude Code、Codex、Kimi Code 等)也是 `AgentRunner`:它们消费 event-first `AgentRunContext`、返回 `AgentRunResult`,并通过 Host 授权的 state/storage/artifact API 保存跨轮次指针。它们内部可以继续使用自己的 session、tool loop、MCP、上下文压缩和权限模型。
## 3. 版本协商
## 3. 协议演进
- `AgentRunnerManifest.protocol_version` 声明 runner 实现的协议大版本,当前为 `"1"`
- `AgentRuntimeContext.protocol_version``ctx.runtime.protocol_version`)声明 Host 下发的协议大版本。
- Host 发现 runner 时校验 `protocol_version` 兼容性;不兼容的 runner 不进入可用列表,只记 warning
- 字段级演进规则:新增可选字段不提升大版本;删除或改语义需要提升大版本
当前 AgentRunner 合同不暴露显式 `protocol_version` 字段。协议演进先按字段级兼容规则处理:
- 新增可选字段保持向后兼容
- 删除字段或改变既有字段语义需要在 SDK 发布前完成;发布后应走新的显式兼容方案
- 结果流演进Host **必须忽略未知 result type 并记录 warning**(除非该 type 明确要求强校验)。新增 result type 不提升大版本。
## 4. Discovery 协议
@@ -68,7 +68,6 @@ class AgentRunnerManifest(BaseModel):
name: str
label: I18nObject
description: I18nObject | None = None
protocol_version: str = "1"
capabilities: AgentRunnerCapabilities
permissions: AgentRunnerPermissions
context: AgentRunnerContextPolicy
@@ -324,7 +323,6 @@ class ContextAPICapabilities(BaseModel):
```python
class AgentRuntimeContext(BaseModel):
host: str = "langbot"
protocol_version: str = "1"
langbot_version: str | None = None
trace_id: str
deadline_at: float | None = None
@@ -548,38 +546,36 @@ Host 必须校验 `state.updated` 的 scope、key、value 大小和 JSON 可序
```python
# Model
await api.models.invoke(model_id, messages, tools=None, extra_args=None)
await api.models.stream(model_id, messages, tools=None, extra_args=None)
await api.models.rerank(model_id, query, documents, top_k=None)
await api.invoke_llm(model_id, messages, funcs=None, extra_args=None)
async for chunk in api.invoke_llm_stream(model_id, messages, funcs=None, extra_args=None):
...
await api.invoke_rerank(rerank_model_id, query, documents, top_k=None)
# Tool
await api.tools.get_detail(tool_name)
await api.tools.call(tool_name, parameters)
await api.get_tool_detail(tool_name)
await api.call_tool(tool_name, parameters)
# Knowledge
await api.knowledge.retrieve(kb_id, query_text, top_k=5, filters=None)
await api.retrieve_knowledge(kb_id, query_text, top_k=5, filters=None)
# History返回 Transcript projection不返回原始平台 payload
await api.history.page(conversation_id=None, before_cursor=None, after_cursor=None,
await api.history_page(conversation_id=None, before_cursor=None, after_cursor=None,
limit=50, direction="backward", include_artifacts=False)
await api.history.search(query, filters=None, top_k=10)
await api.history_search(query, filters=None, top_k=10)
# Event返回稳定 event envelope 或受限 raw ref不默认返回大 payload
await api.events.get(event_id)
await api.events.page(before_cursor=None, limit=50)
await api.event_get(event_id)
await api.event_page(before_cursor=None, limit=50)
# Artifact必须支持大小限制、MIME 校验、过期时间和授权范围)
await api.artifacts.metadata(artifact_id)
await api.artifacts.read_range(artifact_id, offset=0, length=65536)
await api.artifacts.open_stream(artifact_id)
await api.artifact_metadata(artifact_id)
await api.artifact_read_range(artifact_id, offset=0, length=65536)
# State / Storage
await api.state.get(scope, key); await api.state.set(scope, key, value); await api.state.delete(scope, key)
await api.storage.get(area, key); await api.storage.set(area, key, value)
await api.storage.delete(area, key); await api.storage.list(area, prefix=None)
# Platform受限能力默认不开放需 manifest + binding policy + 用户审批同时允许)
await api.platform.request_action(action, target, payload)
await api.state_get(scope, key); await api.state_set(scope, key, value); await api.state_delete(scope, key)
await api.state_list(scope, prefix=None)
await api.get_plugin_storage(key); await api.set_plugin_storage(key, value); await api.delete_plugin_storage(key)
await api.get_workspace_storage(key); await api.set_workspace_storage(key, value); await api.delete_workspace_storage(key)
```
`state``storage` 的建议边界:`state` 放小型 JSONconversation / actor / runner / binding`storage` 放 blob 或较大数据插件私有数据、workspace 数据、checkpoint