Terminus-KIRA原生工具调用实战:告别ICL解析,用tools参数让AI稳定执行终端命令
Terminus-KIRA原生工具调用实战:告别ICL解析,用tools参数让AI稳定执行终端命令
Terminus-KIRA 是 KIRA 项目中的核心 Agent 框架,专为 Terminal-Bench 打造。它用 LLM 原生的 tools 参数实现原生工具调用(Native Tool Calling),彻底告别 ICL(In-Context Learning)JSON/XML 文本解析,让 AI 模型稳定、结构化地执行终端命令,从而显著提升前沿大模型在终端任务上的表现。
为什么 ICL 解析靠不住?
早期的终端 Agent(如 Terminus 2)采用典型的 ICL 方案:在系统提示词里详细规定"请输出如下 JSON 格式的回复",然后用正则/JSON 解析器从模型自由文本里抠出命令。这种方式有两个固有痛点:
- 格式漂移:模型偶尔会输出 XML、带 Markdown 围栏的 JSON、甚至夹带解释文字,解析器一旦失败就整轮空转;
- 提示词冗长:为了保证格式,系统提示词里塞满了 JSON Schema 说明,挤占宝贵的上下文空间。
Terminus-KIRA 的思路非常直接:既然各家 LLM API 都支持 tools 参数,那就把"输出格式约定"交给 API 层,让模型返回结构化的 tool call,代码侧完全不需要写解析容错逻辑。 相关演进记录见 README.md。
3个原生工具一次讲清
所有工具定义集中在 terminus_kira/terminus_kira.py 的 TOOLS 列表中,通过 litellm.acompletion 的 tools=TOOLS 直接传给模型:
| 工具名 | 作用 | 关键参数 |
|---|---|---|
execute_commands |
执行终端命令 | analysis(当前状态分析)、plan(下一步计划)、commands(含 keystrokes 与 duration 的命令数组) |
task_complete |
声明任务完成(触发双重确认) | 无参数 |
image_read |
视觉分析图片文件 | file_path、image_read_instruction |
其中 execute_commands 的参数设计值得学习:analysis 和 plan 是必填字段,强制模型在敲命令前先"看懂现状、说清计划",相当于把思维链固化进了结构里,这也是输出更稳定的重要原因。
从模型响应到命令执行:完整执行回路
整个链路在 TerminusKira 类中实现,分为四步:
- 绕过基础 Chat 类,直连 LLM:_call_llm_with_tools 直接调用
litellm.acompletion并传入tools,从而拿到 API 原生的tool_calls字段,而不是解析自由文本; - 结构化解析:_parse_tool_calls 把 tool call 还原为可执行命令。由于参数本身就是合法 JSON,只需
json.loads一次即可,遇到未知工具名会向模型回传 WARNINGS 让它自我纠正; - 标记轮询执行:_execute_commands 在每条命令后追加
echo '__CMDEND__<seq>__'标记,若标记在duration内出现就立即推进下一条命令,快速命令可以省去大部分等待时间; - 写回对话历史:每个 tool call 都会以
role: "tool"的结果消息写回上下文,保证多轮工具调用符合 OpenAI 风格 API 的消息规范。
4个让 Agent 更稳的工程优化
原生工具调用之外,Terminus-KIRA 还叠加了几个"小而有效"的 harness 层改进:
- 提示词瘦身:迁移到
tools参数后,系统提示词删除了大段 JSON 格式说明,只剩十几行,见 prompt-templates/terminus-kira.txt; - Prompt 缓存:anthropic_caching.py 对最近 3 条消息打
ephemeral缓存标记,降低 Anthropic 模型的延迟与费用; - 输出截断防护:终端输出限制在 30 KB,防止上下文被长日志撑爆;
- 双重完成确认:模型第一次调用
task_complete时,框架会回传一份"测试工程师 / QA 工程师 / 用户"三重视角检查清单,要求模型确认无误后再确认一次,减少"假装完成"。
快速上手:一条命令跑起 Agent
项目已内置本地与云端三类执行脚本,分别对应 Docker、Daytona、Runloop 环境:
核心运行命令如下(以 Docker 环境为例):
uv run harbor run \
--dataset terminal-bench-sample@2.0 \
--n-tasks 1 \
--agent-import-path "terminus_kira.terminus_kira:TerminusKira" \
--model anthropic/claude-opus-4-6 \
--env docker \
-n 1
需要自行部署时,先克隆仓库:
git clone https://gitcode.com/gh_mirrors/kira3/KIRA
cd KIRA
小结
Terminus-KIRA 的实践说明:结构化输出不是靠提示词"求"出来的,而是靠 API 能力"给"出来的。 把命令执行从 ICL 文本解析迁移到 tools 参数后,解析代码更简单、系统提示词更短、模型行为更可控——这正是它在 Codex 5.3、Opus 4.6、Gemini 3.1 Pro 等前沿模型上能取得 75% 左右 Terminal-Bench 成绩的关键。如果你有自己维护的终端 Agent,这套"工具定义 + 标记轮询 + 双重确认"的组合也完全可以照搬复用。

