Agentia — a declarative framework for agent services

01 — CAPABILITIES

Four kinds of capability, one abstraction

Capabilities are what a service is made of. All four kinds sit on the main agent's menu as callable entries — declare once, let the model do the dispatching.

@Tool

Function calls

A class method is a tool. Arguments are parsed against a JSON Schema and validated before execution; a failure comes back as is_error and the run keeps going.

@Skill

Code-driven flow

Call the model on demand from deterministic code: how many times, when to stop, how to post-process — all decided by your code.

@SubAgent

Isolated sub-agents

Its own loop with a trimmed context. Intermediate work stays inside; only the final report flows back to the main context.

@Prompt

Plain-text assets

Templates and playbooks. Pulled into context when the model decides it needs them; supports volatile and static constants.

02 — FEATURES

Built for production

Core

Observable: trace as a first-class citizen

runId == traceId, built in from turn 0. Every model round-trip and capability call is accounted for — tokens, cost, latency, error class — and sub-agents recurse into a tree. One trace exit feeds OTLP or a sink of your own, per-capability and per-model metrics are derived from the trace (nothing to instrument), and agentia report prints a one-line tuning report of which capability is slow / expensive / error-prone.

CLI and directory conventions

create scaffolds, g generates capabilities. One capability per folder, long text in .md; assembly works from either a directory scan or an explicit registry.

Static checks at assembly time

Duplicate menu entries, missing references, DI cycles — all fail at startup, not in production.

Long context and budgets

Drop the oldest tool pairs first, then summarize and compress; the context-budget guardrail carries hysteresis so it does not flap; CJK-aware token estimation. maxTotalTokens / maxCostUsd stop the run hard once accounted, ending with budget_exceeded.

Three trigger modes

Synchronous RPC, asynchronous tasks, and scheduled dispatch share one input contract; idempotent de-duplication, resume from disk.

Capability middleware

CapabilityMiddleware wraps every capability call in an onion model: auth / rate limiting / caching / auditing are all cross-cutting, accounted for at the trace level, with zero intrusion into business capabilities; the host side also gets graceful shutdown and /healthz.

Reflection-free decorators

Standard Stage 3 decorators + explicit DI, no bet on reflect-metadata; works with tsx / esbuild / tsgo.

MCP and evals

An MCP server's tools map onto menu entries in one line — connectors (stdio / StreamableHTTP) are built in and use only the standard library, adding no third-party dependency (the framework still never imports the MCP SDK); defineEval turns "did my prompt change cause a regression?" into assertions over a trace.

03 — QUICKSTART

Running in three minutes

Scaffold

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

Generate capabilities

agentia g subagent doc-reviewer   # isolated sub-agent
agentia g skill note-writer      # code-driven flow
agentia g prompt style-guide     # text asset

Run

# put ANTHROPIC_API_KEY into the .env the scaffold generated
npm run dev

src/tools/weather/index.ts

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

export default class Weather {
  @Tool({
    description: 'Get the weather for a city',
    schema: {
      type: 'object',
      properties: { city: { type: 'string' } },
      required: ['city'],
      additionalProperties: false,
    },
    strict: true,
  })
  get_weather(input: { city: string }) {
    return `Shanghai 72°F sunny (${input.city})`;
  }
}