Agentia — 声明式 Agent 服务开发框架

01 — CAPABILITIES

四类能力，一种抽象

能力是服务的组成部分。四类能力对主 agent 都是菜单里的可调用项——声明一次，调度交给模型。

@Tool

函数调用

类方法即工具。入参按 JSON Schema 解析，先校验再执行；失败回 is_error，run 不中断。

@Skill

代码控制的流程

确定性脚本里按需调模型：调几次、何时停、结果怎么加工，全由代码决定。

@SubAgent

隔离的子代理

独立循环 + 裁剪上下文。中间过程不外泄，只有最终报告回流主上下文。

@Prompt

纯文本资产

模板与 playbook 资产。模型判定需要时拉取进上下文，支持 volatile 与静态常量。

02 — FEATURES

为生产而生

核心

可观测：trace 一等公民

runId == traceId，Turn 0 起内建。每次模型往返与能力调用都记账 —— token、成本、耗时、错误分类，子 agent 递归成树；trace 一条出口接 OTLP 或自建 sink，能力级与模型级指标从 trace 派生（不用埋点），agentia report 一行出「哪个能力慢 / 贵 / 爱失败」的调优报告。

CLI 与目录约定

create 脚手架、g 生成能力。一能力一文件夹，长文本放 .md；目录扫描与显式注册表双装配。

装配期静态校验

菜单查重、引用存在性、DI 循环依赖——在启动时失败，而不是在线上。

长上下文与预算

先丢旧工具对，再摘要压缩，上下文预算护栏带滞回防抖；CJK 感知 token 估算。maxTotalTokens / maxCostUsd 记账后硬停，超限以 budget_exceeded 收尾。

三类触发

同步 RPC、异步任务、定时调度，共用一份输入契约；幂等去重，落盘续跑。

能力中间件

CapabilityMiddleware 洋葱模型包裹每次能力调用：鉴权 / 限流 / 缓存 / 审计皆切面，trace 同级记账，业务能力零侵入；宿主侧另有优雅停机与 /healthz。

零反射装饰器

标准 Stage 3 装饰器 + 显式 DI，不押 reflect-metadata；tsx / esbuild / tsgo 全兼容。

MCP 与 evals

MCP server 的工具一行映射成菜单项（框架零依赖、不含传输）；defineEval 把「改 prompt 有没有回归」变成对 trace 的断言。

03 — QUICKSTART

三分钟跑起来

1

脚手架

npm i -g @migor/cli
agentia create my-app
cd my-app && npm install

2

生成能力

agentia g subagent doc-reviewer   # 独立子代理
agentia g skill note-writer      # 代码控制流程
agentia g prompt style-guide     # 文本资产

3

运行

export ANTHROPIC_API_KEY=sk-ant-...
npm run dev

src/tools/weather/index.ts

import { Tool } from '@migor/agentia';

export default class Weather {
  @Tool({
    description: '查询城市天气',
    schema: {
      type: 'object',
      properties: { city: { type: 'string' } },
      required: ['city'],
      additionalProperties: false,
    },
    strict: true,
  })
  get_weather(input: { city: string }) {
    return `上海 72°F sunny（${input.city}）`;
  }
}