一、背景

从2024 年冬天开始。各类 coding agent 层出不穷——从 Gemini CLI 的起步，到 Claude Code 的尝试，再到如今 Codex、OpenCode、PI、Qoder 等百花齐放。

短短一年多的时间，agent 从大模型的一个附属品。逐渐演变成模型能力的放大器，成为 AI 工程化的关键载体。市面上各类业务 agent——客服、数据分析、工作流编排等——追根溯源，基本都是 coding agent 的泛化变种。

理解了 coding agent 的建立原理，也就掌握了理解其他 agent 的一把钥匙。笔者对每天都在使用的 agent 原理很感兴趣，于是决定自己写一个：violin。不过，

二、效果预览

虽然有点丑。但是基本的功能已经完备了。

三、整体架构

Violin 的架构设计深度借鉴了 Pi 的设计理念。Pi 作为一个 TypeScript 实现的 AI coding agent。其最突出的特点是简洁而可 的架构——三层分离、EventBus 事件驱动、工具注册表和插件程序，每个模块各司其职且松耦合。

更难得的是Pi 的代码完全开源，这不仅让 Violin 有了一个扎实的参考蓝本。也让它本身成为一个极佳的 Agent 工程学习范本：代码结构清晰、注释详尽、每层职责明确。想要学习 Pi 架构的，推荐看看这个项目：

读懂了 Pi 的架构。就理解了现代 AI coding agent 的主要设计模式。Violin 在保持这一架构精髓的同时用 Zig 替换了 TypeScript，在内存安全和性能上做了进一步探索。

Violin agent 的架构如下：

Why Zig?

Violin 的架构设计深度借鉴了 Pi 的三层分离和 EventBus 方案，但在实现语言上做了完全不同的选择。既然每一层通过接口解耦，那么不同层用不同语言实现是完全可行的——不需要也不可能「全部用一种语言写完」。

• 痛点1：语言选择难题- 如果你熟悉 Python。却想追求性能，这里给你提供一种“前后端分离”的思路：后端用 Zig，前端用 Python。
• 痛点2：跨语言通信成本- 两者通过 TCP + JSON line 协议通信。不同语言互不干扰，只需实现统一协议即可。

说到ai，把供应商拍平

不同模型 API 对工具调用、推理内容、缓存、错误、OAuth、流式协议的表达都不同。Violin 把这些差异统一成 Message、Tool、AssistantMessageEvent 和 streamSimple。不过，

• 痛点3：多厂商兼容性挑战- 上层 Agent Loop 不需要知道「这是 Anthropic's tool_use。还是 OpenAI's function call」。只关心统一后的 toolCall 内容块。

agent-core：只管 Agent 运行时

product：把 Agent 变成可用产品

• 痛点4：产品化难度高- 写一个 Agent Loop 并不难。但要把它变成每天能用的软件，需要处理会话管理、多模态支持等“杂七杂八”问题。
• 痛点5：接口标准缺失- 所以我们将 Server 封装为 TCP Server + 通信协议，让任何语言客户端都能接入。

server这方面。把 Agent 能力包装为一个TCP Server

为了让客户端实现与语言无关，需要将 agent 能力包装为一套通信协议 + 一个 TCPServer。TCPServer 流式通信 + 全双工，天生适合这个场景。

四、分层实现介绍

Agent Loop

一个 while 循环。在「问模型」和「执行工具」之间来回切换，直到模型给出最终答案。它不关心模型是 OpenAI 还是 Anthropic，不关心工具是读文件还是跑命令。只关心两件事：

• "模型要不要调工具？"
• "如果要调完继续问；如果不要，则结束"

while {
// 调模型
const assistant = try model.complete(.{
.messages = messages.items。.tools = tool_registry.definitions,});
// 检查是否有工具调用
const has_tool_calls = assistant.toolCalls.len>;说起来，// 没有 → 结束；按理说，有 → 逐个执行工具
if break;不过，for |block| {
if {
const result = tool_registry.execute;messages.append;// 回写给模型
}
}
}

• 为什么要有 max_turns — 模型可能陷入无限工具循环，上限是安全阀。
• 为什么工具结果要 append 回 messages — 模型需要看到结果才能决定接下来。
• 工具可用。

AWS 与 Azure 接口差异导致调试成本飙升？这就是你遇到“tool_call”解析错误时常见的问题：

AI 模型适配层

• 痛点6：“适配多家 LLM provider 时接口繁琐”——我们通过单一 ModelAdapter 接口隐藏差异，让 Agent Loop 完全透明.

interface ModelAdapter {
complete -> AssistantMessage
name -> string
}
// 每个 Provider 实现这个接口：

OpenAIAdapter — 调用 /chat/completions
AnthropicAdapter — 调用 /v1/messagesstruct
CompleteInput {
system_prompt : string。messages : Message,tools : ToolDefinition,max_tokens : int,temperature : float,stream_callback : optional callback,// 流式输出}

stream_callback 示例：

// 模型适配器在收到 SSE 每个 chunk 时调用 streamcallback
// Agent Loop 收到回调后立即通过 EventBus 发射 messageupdate 事件
// Client 收到事件后实时追加到终端显示
pub const StreamCallback = *const fn bool;

{"providers": {
"openai": {
"baseurl": "https://api.openai.com/v1"。"api": "openai-completions","apikey": "$OPENAIAPIKEY","models":
}
}}

Tool System

pub const Tool = struct {
说到name，const u8,description: const u8,parameters: const u8,// JSON Schema
execute: ToolExecuteFn,};

---