Zig Utcp

zig utcp

通用工具调用协议（UTCP） Zig 0.15.2的实现+

LLM工具集成的供应商无关标准，支持HTTP、CLI、MCP、SSE、WebSocket等。

特性

• 零依赖 -仅限纯Zig标准库
• 显式错误处理 -Zig错误接头（无例外）
• Comptime多态性 -通过以下方式进行通用传输 comptime
• 9运输类型 -HTTP、CLI、MCP、SSE、WebSocket、文本、UDP、GraphQL、gRPC
• 4认证方法 -API密钥，基本，承载，OAuth2（带令牌刷新）
• 2台工具装载机 -JSON、OpenAPI
• 流媒体 -增量响应处理
• 后置处理器 -响应转换和验证
• 内存效率高 -请求/响应生命周期的竞技场分配器

v0.2.0中的新功能

• CLI工具 - utcp 测试工具定义命令
• 中间件 -用于日志记录、度量、身份验证注入的请求/响应拦截器
• 断路器 -通过自动恢复防止级联故障
• 速率限制 -令牌桶、滑动窗口和固定窗口算法
• 响应缓存 -基于TTL的缓存，具有可配置的最大条目
• 批量请求 -并行执行多个工具调用
• 调试模式 -详细记录请求/响应时间
• 模式验证 -根据JSON模式验证工具输入
• 模拟运输 -无需网络调用的单元测试
• 重试策略 -瞬态故障时具有抖动的指数回退
• 基准测试 -性能回归测试 zig build bench
• API文件 -生成文档 zig build docs

需求

• Zig 0.15.2或更高版本

安装

选项1：使用 zig fetch （推荐）

zig fetch --save git+https://github.com/bkataru/zig-utcp.git

要获取特定版本，请执行以下操作：

zig fetch --save git+https://github.com/bkataru/zig-utcp.git#v0.1.0

选项2：手动配置

添加到您的 build.zig.zon:

.dependencies = .{
    .utcp = .{
        .url = "git+https://github.com/bkataru/zig-utcp.git",
        .hash = "...", // Run `zig build` to get the correct hash
    },
},

选项3：本地路径依赖

.dependencies = .{
    .utcp = .{
        .path = "../zig-utcp",
    },
},

配置 build.zig

const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // Fetch the utcp dependency
    const utcp_dep = b.dependency("utcp", .{
        .target = target,
        .optimize = optimize,
    });

    // Get the module from the dependency
    const utcp_mod = utcp_dep.module("utcp");

    // Create your executable
    const exe = b.addExecutable(.{
        .name = "my_tool_client",
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/main.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });

    // Add the utcp import to your executable
    exe.root_module.addImport("utcp", utcp_mod);

    b.installArtifact(exe);
}

从源头构建

# Clone the repository
git clone https://github.com/bkataru/zig-utcp.git
cd zig-utcp

# Build the library
zig build

# Run tests
zig build test

# Build examples
zig build examples

# Build release version
zig build -Doptimize=ReleaseFast

快速开始

const std = @import("std");
const utcp = @import("utcp");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Create HTTP transport
    var transport = utcp.HttpTransport.init(allocator);
    defer transport.deinit();
    try transport.loadEnv();

    // Define a tool
    const weather_tool = utcp.Tool{
        .id = "weather_api",
        .name = "Get Weather",
        .description = "Fetch current weather for a city",
        .call_template = .{
            .http = .{
                .method = "GET",
                .url = "https://wttr.in/{city}?format=j1",
                .timeout_ms = 30000,
            },
        },
    };

    // Prepare request
    var inputs_obj = std.json.ObjectMap.init(allocator);
    defer inputs_obj.deinit();
    try inputs_obj.put("city", .{ .string = "London" });

    const request = utcp.ToolCallRequest{
        .tool_id = "weather_api",
        .inputs = .{ .object = inputs_obj },
    };

    // Call the tool
    const response = try transport.call(weather_tool, request, null);
    std.debug.print("Response: {any}\n", .{response.output});
}

例子

运行附带的示例：

# HTTP client (calls wttr.in weather API)
zig build run-http

# CLI client
zig build run-cli

# MCP client
zig build run-mcp

# Streaming example
zig build run-streaming

# Post-processor example
zig build run-postprocessor

# OAuth2 example
zig build run-oauth2

# UTCP CLI tool
zig build run-utcp -- help
zig build run-utcp -- info
zig build run-utcp -- load tools.json

看 examples/ 查看完整的工作示例。

API 参考

核心类型

运输

装载机

流媒体

const stream = utcp.fromBytes(allocator, data);
defer stream.deinit();

while (stream.next()) |chunk| {
    // Process chunk
    if (chunk.is_final) break;
}

后置处理器

var chain = utcp.PostProcessorChain.init(allocator);
defer chain.deinit();

try chain.addFn("trim", utcp.trimProcessor);
try chain.addFn("log", utcp.logProcessor);
try chain.process(&response);

中间件

var chain = utcp.MiddlewareChain.init(allocator);
defer chain.deinit();

// Add logging middleware
try chain.add(.{
    .name = "logger",
    .on_request = logRequest,
    .on_response = logResponse,
});

// Process request through middleware
try chain.processRequest(&context);
const response = try transport.call(tool, request, provider);
try chain.processResponse(&context, &response);

断路器

var breaker = utcp.CircuitBreaker.init(.{
    .failure_threshold = 5,
    .reset_timeout_ms = 30000,
});

if (breaker.canExecute()) {
    const result = transport.call(tool, request, provider);
    if (result) |resp| {
        breaker.recordSuccess();
    } else |_| {
        breaker.recordFailure();
    }
}

速率限制

var limiter = utcp.TokenBucket.init(.{
    .burst_size = 100,
    .refill_rate = 10.0, // tokens per second
});

if (limiter.tryAcquire()) {
    // Proceed with request
} else {
    // Rate limited
}

响应缓存

var cache_inst = utcp.ResponseCache.init(allocator, .{
    .max_entries = 1000,
    .default_ttl_ms = 300000, // 5 minutes
});
defer cache_inst.deinit();

// Check cache
if (cache_inst.get(cache_key)) |cached| {
    return cached;
}

// Make request and cache
const response = try transport.call(tool, request, provider);
try cache_inst.put(cache_key, response);

模拟运输（测试）

var mock = utcp.MockTransportBuilder.init(allocator)
    .expectCall("weather_api", .{ .output = .{ .string = "{\"temp\":20}" } })
    .expectCall("translate", .{ .output = .{ .string = "Bonjour" } })
    .build();
defer mock.deinit();

const response = try mock.call(tool, request, null);
try mock.verify(); // Fails if expectations not met

建筑

src/
├── core/              # Core types
│   ├── tool.zig       # Tool, ToolCallRequest, ToolCallResponse
│   ├── provider.zig   # Provider, Auth types
│   ├── errors.zig     # Error types
│   ├── substitution.zig  # Variable substitution
│   ├── streaming.zig  # Streaming responses
│   ├── postprocessor.zig # Post-processors
│   ├── middleware.zig # Request/response interceptors
│   ├── circuit_breaker.zig # Circuit breaker pattern
│   ├── rate_limit.zig # Rate limiting algorithms
│   ├── cache.zig      # Response caching
│   ├── batch.zig      # Batch request execution
│   ├── validation.zig # JSON Schema validation
│   ├── debug.zig      # Debug logging
│   ├── retry.zig      # Retry policies
│   └── mock.zig       # Mock transport for testing
├── repository/
│   └── memory.zig     # InMemoryToolRepository with search
├── transports/        # Transport implementations
├── loaders/           # Tool loaders (JSON, OpenAPI)
├── cli.zig            # CLI tool
└── utcp.zig           # Public API

看 docs/ARCHITECTURE.md 详细设计。

项目状态

Go/Rust/TypeScript实现的100%特性奇偶校验

贡献

欢迎投稿！请随时提交拉取请求。

许可证

MIT许可证-请参阅 许可证 了解详情。

相关项目

• UTCP规范
• UTCP Go
• UTCP锈蚀
• UTCP TypeScript