AI Agent 的上下文工程层。仅为每轮对话选择相关的工具与技能，恢复因工具过载而损失的准确度，并削减每次调用的费用。无需向量数据库，无需基础设施。

• 成本： 每条工具 schema、每个技能以及系统提示中不断增长的指令，都是每次调用需要付费的 token。如果一开始就把它们全部发送，每一轮都要为它们付费。
• 准确度： 当上下文膨胀时，模型表现会变差。用本轮不需要的工具、技能和指令填满上下文，模型就会选错选项并偏离任务。
• Ratel 同时解决两者： 它将工具与技能索引到一个目录中，代理可以渐进披露，为每一轮搜索所需内容，仅注入匹配的能力，而不是预先加载全部。

在本地、开源和前沿模型环境中，Ratel 均能削减 token 使用并恢复工具过载损失的准确度，无需向量数据库。完整结果见：benchmark.ratel.sh

指南：Quickstart · TypeScript SDK · Python SDK

示例：Vercel AI SDK · Pydantic AI

首先安装 SDK：

然后创建并使用你的目录：

import { readFile } from "node:fs/promises"; import { SkillCatalog, ToolCatalog, getSkillContentTool, invokeToolTool, searchCapabilitiesTool, } from "@ratel-ai/sdk";

const catalog = new ToolCatalog(); catalog.register({ id: "read_file", name: "read_file", description: "Read a file from local disk.", inputSchema: { type: "object", properties: { path: { type: "string" } } }, outputSchema: { type: "object", properties: { contents: { type: "string" } } }, execute: async ({ path }) => ({ contents: await readFile(path, "utf8") }), });

const skills = new SkillCatalog(); skills.register({ id: "inspect-local-file", name: "inspect-local-file", description: "Inspect a local file before answering questions about it.", tools: ["read_file"], body: "Read the requested file, then ground your answer in its contents.", });

// use the following as tools in your agent framework const search = searchCapabilitiesTool(catalog, skills); const invoke = invokeToolTool(catalog); const loadSkill = getSkillContentTool(skills);

首先安装 SDK：

然后创建并使用你的目录：

from ratel_ai import ( ExecutableTool, Skill, SkillCatalog, ToolCatalog, get_skill_content_tool, invoke_tool_tool, search_capabilities_tool, )

catalog = ToolCatalog() catalog.register(ExecutableTool( id="read_file", name="read_file", description="Read a file from local disk.", input_schema={"properties": {"path": {"type": "string"}}}, execute=lambda args: {"contents": open(args["path"]).read()}, ))

skills = SkillCatalog() skills.register(Skill( id="inspect-local-file", name="inspect-local-file", description="Inspect a local file before answering questions about it.", tools=["read_file"], body="Read the requested file, then ground your answer in its contents.", ))

use the following as tools in your agent framework

search = search_capabilities_tool(catalog, skills) invoke = invoke_tool_tool(catalog) load_skill = get_skill_content_tool(skills)

当你的 Agent 需要行动时，它调用 search_capabilities。Ratel 分别搜索工具索引和技能索引，并返回各自的聚焦结果。工具可以通过 id 调用；技能指令在选择加载相关 playbook 之前不会出现在上下文中，通过 get_skill_content 实现。

索引默认使用 BM25，这是多数搜索引擎背后的算法，应用于模式感知的工具元数据以及技能名称、描述和标签。检索快速且确定性。语义及混合排序可按目录或按调用选择加入；SDK 调用者通过注册（会进行嵌入）并异步搜索稠密索引，可使用进程内模型或兼容 OpenAI 的嵌入端点。

完整文档

相关开源项目扩展并验证了此仓库：

src/ ├── core/ # ratel-ai-core — Rust 检索引擎 ├── sdk/ts/ # @ratel-ai/sdk — TypeScript SDK (NAPI 绑定) ├── sdk/python/ # ratel-ai — Python SDK (PyO3 绑定) └── telemetry/ # OTel 约定与辅助包 protocol/ # catalog-source 通信契约 examples/ # 端到端 SDK 示例 docs/ ├── adr/ # 架构决策记录 └── assets/ # 图片及其他静态资源

前提条件：Rust 稳定版，Node 24+，pnpm 10.28+。Python SDK：Python 3.9+ 及 uv。

cargo build --workspace && cargo test --workspace # Rust pnpm install && pnpm -r build && pnpm -r test # TypeScript

Python: 参见 src/sdk/python/README.md

ratel-ai-core 引擎采用 Apache-2.0 许可——为其他项目嵌入该引擎提供明确专利授权。其余所有内容（SDK、遥测辅助、示例）采用 MIT 许可。相关理由参见 ADR-0009。

The context engineering layer for AI agents. Selects only the tools and skills relevant to each turn, recovering accuracy lost to tool overload and cutting what you pay per call. No vector DB, no infra.

• Cost: Every tool schema, every skill, and a growing list of instructions in the system prompt are tokens you pay for on every call. Send them all up front and you pay for them all, every turn.
• Accuracy: Models get worse as that context grows. Crowd it with tools, skills, and instructions a turn doesn't need and the model picks the wrong option and drifts off task.
• Ratel fixes both: it indexes your tools and skills into a catalog the agent progressively discloses , searching for what each turn needs and injecting only the matching capabilities instead of loading everything up front.

Across local, open-source, and frontier model setups, Ratel cuts token usage and recovers accuracy lost to tool overload, with no vector DB required. Full results: benchmark.ratel.sh

Guides: Quickstart · TypeScript SDK · Python SDK

Examples: Vercel AI SDK · Pydantic AI

Install the SDK first:

Then create and use your Catalogs:

import { readFile } from "node:fs/promises";
import {
  SkillCatalog,
  ToolCatalog,
  getSkillContentTool,
  invokeToolTool,
  searchCapabilitiesTool,
} from "@ratel-ai/sdk";

const catalog = new ToolCatalog();
catalog.register({
  id: "read_file",
  name: "read_file",
  description: "Read a file from local disk.",
  inputSchema: { type: "object", properties: { path: { type: "string" } } },
  outputSchema: { type: "object", properties: { contents: { type: "string" } } },
  execute: async ({ path }) => ({ contents: await readFile(path, "utf8") }),
});

const skills = new SkillCatalog();
skills.register({
  id: "inspect-local-file",
  name: "inspect-local-file",
  description: "Inspect a local file before answering questions about it.",
  tools: ["read_file"],
  body: "Read the requested file, then ground your answer in its contents.",
});

// use the following as tools in your agent framework
const search = searchCapabilitiesTool(catalog, skills);
const invoke = invokeToolTool(catalog);
const loadSkill = getSkillContentTool(skills);

Install the SDK first:

Then create and use your Catalogs:

from ratel_ai import (
    ExecutableTool,
    Skill,
    SkillCatalog,
    ToolCatalog,
    get_skill_content_tool,
    invoke_tool_tool,
    search_capabilities_tool,
)

catalog = ToolCatalog()
catalog.register(ExecutableTool(
    id="read_file",
    name="read_file",
    description="Read a file from local disk.",
    input_schema={"properties": {"path": {"type": "string"}}},
    execute=lambda args: {"contents": open(args["path"]).read()},
))

skills = SkillCatalog()
skills.register(Skill(
    id="inspect-local-file",
    name="inspect-local-file",
    description="Inspect a local file before answering questions about it.",
    tools=["read_file"],
    body="Read the requested file, then ground your answer in its contents.",
))

# use the following as tools in your agent framework
search = search_capabilities_tool(catalog, skills)
invoke = invoke_tool_tool(catalog)
load_skill = get_skill_content_tool(skills)

When your agent needs to act, it calls search_capabilities. Ratel searches separate tool and skill indexes and returns focused results from each. Tools can be invoked by id; skill instructions stay out of context until the agent loads a relevant playbook with get_skill_content.

The indexes use BM25 by default, the same algorithm behind most search engines, applied to schema-aware tool metadata and skill names, descriptions, and tags. Retrieval is fast and deterministic. Semantic and hybrid ranking are opt-in per catalog or per call; SDK callers register (which embeds) and search dense indexes asynchronously, using either an in-process model or an OpenAI-compatible embedding endpoint.

Full docs

Related open-source projects extend and validate this repository:

src/
├── core/              # ratel-ai-core — Rust retrieval engine
├── sdk/ts/            # @ratel-ai/sdk — TypeScript SDK (NAPI-bound)
├── sdk/python/        # ratel-ai — Python SDK (PyO3-bound)
└── telemetry/         # OTel conventions + helper packages
protocol/              # catalog-source wire contract
examples/              # End-to-end SDK examples
docs/
├── adr/                # Architecture decision records
└── assets/             # Images and other static assets

Prerequisites: Rust stable, Node 24+, pnpm 10.28+. Python SDK: Python 3.9+ and uv.

cargo build --workspace && cargo test --workspace   # Rust
pnpm install && pnpm -r build && pnpm -r test       # TypeScript
# Python: see src/sdk/python/README.md

The ratel-ai-core engine is licensed under Apache-2.0 — an explicit patent grant for the engine others embed. Everything else (SDKs, telemetry helpers, examples) is MIT. See ADR-0009 for the rationale.