AI导哈

HTTP API自描述协议

HALO是一种轻量级协议规范，允许任何HTTP API通过标准OPTIONS动词和自定义Accept头部向LLM代理自我描述，无需注册中心或代理层。

  • by irarainey
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 irarainey/halo

使用说明

HALO-用于操作的HTTP API语言

LLM代理的自描述API——无需MCP。

HALO是一种轻量级协议约定，允许任何HTTP API使用标准向LLM代理描述自己 OPTIONS 动词与风俗 Accept: application/llm+json 头球没有注册表，没有sidecar进程，没有代理层——只有描述自己的API。

此存储库包含：

  • HALO协议规范 --完全语言和平台无关的协议规范(halo-规范.md)
  • halo-fastapi --一个提供FastAPI服务器端插件的Python包(HaloRegister)，代理端客户端(HaloClient)，以及用于Microsoft代理框架的框架适配器(HaloAgentFrameworkAdapter)语义内核(HaloSemanticKernelAdapter)
  • API样本 --一个跨四个域实现HALO兼容端点的FastAPI服务器
  • 样本代理（代理框架） --使用Microsoft agent Framework的基于浏览器的DevUI的LLM代理
  • 示例代理（语义内核） --一个使用语义内核进行交互式CLI聊天的LLM代理

运作原理

1. OPTIONS /                     → discover all available tools
2. OPTIONS /api/payments/charge  → fetch full schema for a specific tool
3. POST /api/payments/charge     → call the API directly — no proxy

LLM代理发送 OPTIONS / 随着 Accept: application/llm+json 获取所有可用工具的清单——它们的名称、描述和标签。当它选择一个工具时，它会发送 OPTIONS 访问该特定端点以获取完整模式。然后它直接调用真正的端点。

工具可以通过标签进行筛选(OPTIONS /?tags=payments)因此，代理只会发现与他们的任务相关的内容。

架构响应示例

[
  {
    "description": "Charge a payment method for a given amount",
    "call":    { "method": "POST", "url": "/api/payments/charge" },
    "auth":    { "type": "bearer", "scopes": ["payments:write"] },
    "input":   {
      "amount":      { "type": "number", "required": true },
      "currency":    { "type": "string", "enum": ["GBP", "USD", "EUR"] },
      "customer_id": { "type": "string", "required": true }
    },
    "output":  { "charge_id": { "type": "string" }, "status": { "type": "string" } },
    "why":     "Use to charge a customer immediately. Prefer /authorise for pre-auth flows.",
    "effects": { "reversible": true, "undo": "/api/payments/refund" },
    "tags":    ["payments", "write"]
  }
]

主要特点

  • 零结构漂移 --结构字段（输入、输出、类型、身份验证）来自处理请求的同一代码。LLM原生油田(why, tags, effects)手写，但与模型位于同一位置。
  • 标签筛选发现 --代理仅通过以下方式发现与其任务相关的工具 OPTIONS /?tags=payments.
  • 授权感知范围 --传递令牌 OPTIONS / 清单只反映了这些证书允许的内容。
  • 延迟加载 --只有当代理选择工具时，才会获取完整的模式，从而降低令牌成本。
  • 直接呼叫路径 --没有代理层。代理直接调用API。两跳：代理→ API.
  • 凭证注入 — HaloClient 在调用时从凭证映射注入承载令牌、API密钥或基本身份验证。
  • 使用回退重试 — HaloClient 在429和5xx响应上以指数回退重试失败的请求。

安装

uv add halo-fastapi

服务器使用情况（FastAPI）

一条线路使每条路线都符合HALO标准：

from halo_fastapi import HaloRegister
from fastapi import FastAPI

app = FastAPI(title="My API", version="1.0.0")
HaloRegister(app)  # registers OPTIONS handlers automatically

输入/输出模式、身份验证要求和描述都来自现有的Pydantic模型、路由装饰器和依赖注入，不需要额外的配置。LLM原生字段，如 why, tags，以及 effects 可以通过以下方式添加 json_schema_extra 在你的Pydantic模型上。

客户端使用情况（代理适配器）

from halo_fastapi import HaloClient

plugin = await HaloClient(
    base_url="https://api.example.com",
    bearer_token=os.getenv("API_KEY"),
).discover(tags=["payments"])

# Fetch a single tool schema
schema = await plugin.get_tool("/api/payments/charge")

# Invoke a tool directly
result = await plugin.invoke("/api/payments/charge", body={"amount": 1000, "currency": "GBP", "customer_id": "cust_123"})

HALO替代什么

之前 与HALO
MCP服务器进程 现有API内部的OPTIONS处理程序
工具注册表 API是注册表
架构漂移 结构字段不能漂移--源自代码
代理层/额外跃点 代理直接调用API
静态工具定义 通过OPTIONS进行动态发现
前期代币成本 延迟、标签过滤加载

规格

完整的协议规范见 halo-规范.md该协议与语言和平台无关——任何语言的HTTP服务器都可以实现HALO。

运行示例

该存储库包括一个预先配置了所有工具的开发容器。使用Dev Containers扩展在VS Code中打开。

Poe任务

命令 描述
poe api 在端口3010上启动示例API
poe maf 启动代理框架DevUI（需要API）
poe sk 启动语义内核CLI聊天（需要API）
poe sync:maf 代理框架的同步依赖关系
poe sync:sk 语义内核的同步依赖关系
poe test 运行单元测试
poe lint 跑ruff和mypy
poe format 自动格式化代码
poe build 构建 halo-fastapi 包装

VS代码启动配置文件

简介 描述
示例API+代理框架 两者都开始；首先同步MAF依赖关系
示例API+语义内核 两者都开始；首先同步SK依赖关系

注： 代理框架和语义内核示例具有冲突的传递依赖关系，不能同时安装。使用 poe sync:maf 或 poe sync:sk 在它们之间切换。

存储库结构

halo/
├── halo-specification.md      # Full protocol specification (CC BY 4.0)
├── halo-fastapi/              # Python reference implementation (Apache 2.0)
│   └── src/halo_fastapi/
│       ├── _schema.py         # HaloRegister server-side plugin
│       ├── _client.py         # HaloClient client-side HTTP adapter
│       ├── _types.py          # Pydantic models for HALO schema types
│       ├── _constants.py      # Shared constants (content type, defaults)
│       └── adapters/
│           ├── _agent_framework_adapter.py  # Agent Framework integration
│           └── _semantic_kernel_adapter.py  # Semantic Kernel integration
├── samples/                   # Sample applications
│   ├── agents/
│   │   ├── agent-framework/   # Microsoft Agent Framework sample
│   │   │   └── src/sample_agent_framework/
│   │   └── semantic-kernel/   # Semantic Kernel sample
│   │       └── src/sample_semantic_kernel/
│   └── servers/
│       └── fastapi/           # HALO-compliant demo API
│           ├── data/          # JSON data files (weather, books, inventory, employees)
│           └── src/sample_api/

许可证

相关 MCP