Guide

Quickstart

Agentia is a declarative framework for agent services: decorators declare four kinds of capability, the main agent acts as a router and orchestrates them, and one run hands back structured output plus a complete call tree (runId == traceId) with tokens / cost / metrics accounted for all the way down — replayable and auditable. Running in three minutes:

npm i -g @migor/cli
agentia create my-app        # scaffold: four category folders + src/registry.ts + .env
cd my-app && npm install
agentia g subagent doc-reviewer  # generate a capability and register it automatically
# put ANTHROPIC_API_KEY into the .env the scaffold generated (.gitignore already covers it)
npm run dev -- "review docs/report.md for me"

The entry point src/main.ts does exactly one thing: assemble the app, then trigger a run.

import { createApp, SystemPrompt } from '@migor/agentia';

const app = await createApp({
  name: 'my-app',
  discover: ['src/tools', 'src/skills', 'src/prompts', 'src/subagents'], // four category folders; order is assembly order
  system: new SystemPrompt().add('role', 'You are the main agent of my-app; dispatch the capabilities on your menu as the task requires.', true),
});

const { result } = await app.run([{ role: 'user', content: process.argv[2] }]);
console.log(result.finalText);

Scenario guide

Find the recipe by what you want to do: five cards, each with a minimal skeleton and a link to go deeper. Every API and command matches docs/usage-guide.md word for word.

Ship an HTTP agent service

One handler serves synchronous POST /run (SSE when Accept: text/event-stream is set), asynchronous POST /tasks (de-duplicated by idempotency key) and the GET /healthz probe. Auth goes through the authenticate seam (it intercepts before the body is read) and shutdown goes through drain — unfinished tasks stay in the store, and resumePending() picks them up after a restart.

import { createServer } from 'node:http';
import { createApp, createHttpHandler, AsyncRunner, SqliteTaskStore, HttpException } from '@migor/agentia';

const app = await createApp({ name: 'my-app', providers, system });
const runner = new AsyncRunner(app, { store: new SqliteTaskStore('./tasks.db') });
await runner.resumePending(); // restart resumes queued/running, it does not discard them

const handler = createHttpHandler(app, {
  runner,
  authenticate: async (req) => {
    if (!verify(req.headers.authorization)) throw new HttpException(401, { error: 'invalid credentials' });
  },
});
createServer(handler).listen(8080);
// POST /run (sync / SSE)  POST /tasks (async)  GET /tasks/:id  GET /healthz
process.on('SIGTERM', () => handler.drain({ timeoutMs: 15_000 })); // signal handling belongs to the host

See “Trigger modes” and “Host hardening”; for a complete runnable example (four capabilities + three trigger modes + auth + the full observability stack + a Dockerfile) see examples/complete.

Want to add a gRPC entry point as well: that is a host-side concern, and the framework does not build it in (there is exactly one rule — is the client in the standard library: the MCP connector can be built with spawn + fetch and adds no dependency, whereas gRPC would pull in @grpc/grpc-js). The recipe is in docs/usage-guide.md §6.2, and a host + client + end-to-end you can copy is in examples/grpc-host — it spells out the four semantics most easily missed: deadline / cancellation → signal, metadata traceparent → run-root link, framework errors → gRPC status codes, trace → sink.

Put monitoring on a run

Metrics and trace go through the same seam: metricsSink() satisfies TraceSink, and wiring it into sinks gives you the agentia_* metric family (four levels: run / capability / model / score, where scores come from attachScore as agentia_score / agentia_score_total); createOtlpExporter aligns with the OTel GenAI semconv on export (gen_ai.* keys, recognised directly by Langfuse / Grafana / Datadog).

import { metricsSink, createOtlpExporter } from '@migor/agentia';

const metrics = metricsSink();
const app = await createApp({
  name: 'my-app', providers, system,
  sinks: [metrics, createOtlpExporter({ endpoint: 'http://localhost:4318' })],
});
createHttpHandler(app, { metrics }); // built-in GET /metrics (unauthenticated, still answers while draining)

The Grafana dashboard JSON ships with the repo (examples/observability/grafana-dashboard.json, built against the default prefix of metricsSink — import and use). See “Observability” and “Ecosystem & observability”.

Offline evals and harvesting from production

defineEval + scriptedClient run offline in CI: scripted model round-trips with assertions written against the trace; each case automatically attachScores its verdict onto its trace (value 0|1, source is the eval name), which a downstream metricsSink can aggregate into a pass rate. For production incidents, agentia harvest turns them back into eval case skeletons.

import { defineEval, scriptedClient } from '@migor/agentia';

const report = await defineEval({
  name: 'doc-review',
  app: () => app,
  cases: [{ input: 'Summarise this document', client: scriptedClient([searchMsg, submitMsg]) }],
  expect: (r, { trace }) => { /* assert stopReason / tool sequence / result.typed */ },
}).run();
if (!report.ok) process.exit(1); // failing cases carry the full trace; in CI you only read report.ok

agentia harvest trace.jsonl --failed --limit 5 --out evals/harvested.ts  # production trace → eval case skeleton

A skeleton is not a finished test: the trace does not record assistant text (so the script holds placeholders), and the pre-filled expect transcribes what actually happened (which is not the same as what should happen) — review it by hand before it enters CI. See “Ecosystem & observability” and “CLI reference”.

prompt / model A/B

Run the same input through two runs (swap the model or the SystemPrompt version) and let diffTraces surface the structural and cost differences. Without writing code, agentia diff compares two on-disk traces directly and exits 1 when they differ, so CI can block “the trajectory drifted after a prompt / model change”. To “re-run from turn N with a different question”, use forkMessages — it produces a set of messages you feed back into app.run, which starts a new run, not a continuation.

import { diffTraces, forkMessages } from '@migor/agentia';

const a = await app.run(input, { model: 'claude-sonnet-5' });
const b = await app.run(input, { model: 'claude-opus-5' });
const diff = diffTraces(a.result.trace, b.result.trace); // run-level summary + per-span field diff

// Forked replay: truncate before turn 3 of the main loop (0-based) and continue with a different question
const messages = forkMessages(a.result.trace, {
  atTurn: 3,
  append: [{ role: 'user', content: 'Different angle: give me the conclusion first, then the evidence.' }],
});
const c = await app.run(messages); // a new run, continuing from the real tool history before the fork point

agentia diff a.jsonl b.jsonl   # compare two on-disk traces (same input shape as agentia report); exits 1 when they differ

See “CLI reference”; for the lossy boundaries (the trace records neither assistant text nor the original input) see the Known boundaries section and the A/B part of /llms-full.txt.

Human gate (HITL)

Middleware can await a human decision before letting a call through, and the engine will wait for the tool result: allow = next(); reject = do not call next() (short-circuit, the side effect never happens); reject and redirect the model = throw (the result is recorded as is_error and the run continues).

import type { CapabilityMiddleware } from '@migor/agentia';

const requireApproval: CapabilityMiddleware = async (call, next) => {
  if (!DANGEROUS.has(call.capability.name)) return next();
  const ok = await askHuman(call.capability.name, call.input); // the run simply waits here, for a person
  if (!ok) throw new Error(`not approved: ${call.capability.name}`); // → is_error, the model takes another route
  return next();
};
createApp({ system, providers, middleware: [requireApproval] });

Cross-process suspend / resume is supported: once you declare @Tool({ approval: 'required' }), every model call suspends the task as suspended (message history and the pending list are persisted with the task, so a restart loses nothing), and POST /tasks/:id/approve resumes from the breakpoint with that decision — see “Cross-cutting recipes” and the API reference.

Four capability kinds

Capabilities are what a service is made of. All four kinds sit on the main agent's menu as callable entries, share one namespace, and are de-duplicated at assembly time.

@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.

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})`;
  }
}

@Skill — code-driven flow

The method body is a deterministic script: whether to call the model, how many times, and how to post-process the result are all decided by code. Model calls happen only at an explicit ctx.llm(), accounted for as an llm.turn under the skill's own capability span.

import { Skill } from '@migor/agentia';
import type { SkillContext } from '@migor/agentia';

export default class WeeklyReport {
  @Skill({
    description: 'Ask the LLM for key points on a given topic',
    schema: {
      type: 'object',
      properties: { topic: { type: 'string' } },
      required: ['topic'],
      additionalProperties: false,
    },
  })
  async weekly_report(input: { topic: string }, ctx: SkillContext) {
    const r = await ctx.llm({ prompt: `Give three key points on "${input.topic}"` });
    return r.text; // the return value is the product, handed back to the main agent as a tool_result
  }
}

@SubAgent — isolated sub-agents

Its own loop with a trimmed context. The method body never executes — the framework starts another agent from the system you gave it; intermediate work stays inside and only the final report flows back to the main context.

import { SubAgent, asset } from '@migor/agentia';

export default class DocReviewer {
  @SubAgent({
    description: 'Review a document independently, in the role set by system.md',
    schema: {
      type: 'object',
      properties: { task: { type: 'string' } },
      required: ['task'],
      additionalProperties: false,
    },
    system: asset(import.meta.url, './system.md'),
  })
  // the method body never runs: only the method name and decorator metadata are read
  doc_reviewer(_input: { task: string }): void {}
}

@Prompt — plain-text assets

Templates and playbooks, compiled into a side-effect-free fetch tool on the menu: the model calls it when it decides it needs the text, and the text is injected into context as a tool_result. Long text lives in a sibling .md file.

import { Prompt, asset } from '@migor/agentia';

export default class StyleGuide {
  @Prompt({ description: 'Writing conventions (the description says when to fetch it)' })
  style_guide(): string {
    return asset(import.meta.url, './asset.md');
  }
}

Layout & assembly

Four category folders, one folder per capability, long text in .md files; each capability is a class with a default export whose decorator declares what it is.

my-app/
├─ src/
│  ├─ main.ts                    # createApp assembly entry point
│  ├─ registry.ts                # explicit registry (kept up to date by agentia g)
│  ├─ tools/weather/index.ts     # @Tool
│  ├─ skills/weekly-report/      # @Skill
│  ├─ prompts/style-guide/       # @Prompt (with asset.md)
│  └─ subagents/doc-reviewer/    # @SubAgent (with system.md)
└─ tsconfig.json                 # include: ['src'] — one src covers everything

Two assembly routes

• Directory scan: createApp({ discover: ['src/tools', …] }) takes one directory or a list of them (order is assembly order), scans <name>/index.ts in each at startup, and registers a default-exported class under the folder name as its DI token (because it uses dynamic import, a createApp with discover returns a Promise).
• Explicit registry: createApp({ providers, system }), where providers comes from src/registry.ts (maintained automatically by agentia g).

Use either route or mix the two; for the same token the later one wins and the menu is never collected twice. Assembly runs static checks: duplicate menu entries, reference existence, DI cycles — all failing at startup rather than in production.

Middleware (CapabilityMiddleware)

Hooks around every capability call (tool / skill / subagent / prompt): auth, rate limiting, result caching, audit logging, timeout wrapping and other cross-cutting concerns live here, not inside business capabilities.

type CapabilityMiddleware = (call: CapabilityCall, next: CapabilityNext) => unknown;

interface CapabilityCall {
  readonly capability: AgentTool;   // name / description / inputSchema are readable
  readonly input: unknown;   // arguments that already passed schema validation
  readonly ctx?: ToolRunContext;
}
// Pass through to the next layer; next(newInput) can rewrite the arguments, default keeps the current input
type CapabilityNext = (input?: unknown) => unknown;

The onion model

• Chain order = registration order: the first registered is the outermost layer, wrapping like an onion;
• next() passes through, next(newInput) rewrites the arguments; not calling next short-circuits (result caching, for instance);
• Throwing is treated as a capability failure: the engine wraps it into is_error for the model and the run continues;
• Wrapping happens at assembly time (in the AgentApp constructor) with zero intrusion into the engine; an empty chain passes straight through at no cost.

const app = await createApp({
  name: 'my-app',
  discover: ['src/tools', 'src/skills', 'src/prompts', 'src/subagents'],
  middleware: [auth, cached], // auth is the outermost layer
  system,
});

Example: auth

import type { CapabilityMiddleware } from '@migor/agentia';

// Sensitive capabilities require an authorisation marker in the execution context, otherwise fail as a capability error
export const auth: CapabilityMiddleware = (call, next) => {
  if (call.capability.name.startsWith('admin:') && !call.ctx) {
    throw new Error('forbidden: missing execution context');
  }
  return next();
};

Example: result caching

import type { CapabilityMiddleware } from '@migor/agentia';

const store = new Map<string, unknown>();

// A hit short-circuits (next is not called); a miss passes through and writes back
export const cached: CapabilityMiddleware = async (call, next) => {
  const key = `${call.capability.name}:${JSON.stringify(call.input)}`;
  if (store.has(key)) return store.get(key);
  const out = await next();
  store.set(key, out);
  return out;
};

Trigger modes

Synchronous RPC, asynchronous tasks and scheduled dispatch share one input contract; swapping the host does not change the semantics.

Synchronous RPC

await app.run(messages) hands back the result and the trace directly — a good fit for request-response hosts.

Asynchronous tasks

AsyncRunner returns a task record as soon as you submit and runs it in the background; FileTaskStore snapshots one JSONL line at a time, and after a host restart resumePending() picks queued/running tasks back up.

const task = await runner.submit(
  [{ role: 'user', content: 'Generate last week\u2019s ops report' }],
  { idempotencyKey: 'weekly-report:2026-W36' },
);

Scheduled dispatch

The Scheduler supports every (interval) and at (fixed time) schedules, turning a due schedule into an asynchronous task submission.

Idempotency

The async host has at-least-once semantics: submitting the same idempotencyKey again returns the existing record as long as the previous task has not failed (last-wins de-duplication); a failed task under the same key may be resubmitted as a new task.

Long-context policy

createBudgetPolicy provides a budget-driven context guardrail whose rules carry hysteresis, so it does not compress over and over on every turn:

• Estimate tokens for the whole message set; at or under budget → pass through unchanged (the fast path);
• Over budget, first do context editing: drop the oldest tool pairs, without extra model calls;
• Still over budget and a summarize is available → compaction: turn the old prefix into a summary and keep only the most recent keepRecent items; if fewer than compactEvery turns have passed since the last compaction, skip (anti-flapping);
• The framework does not invent tokens for you: the default token estimate is a CJK-aware heuristic, and you can inject one backed by /count_tokens in production.
• Only new messages are estimated: history is append-only, so the prefix estimate is reused, which makes each turn's estimation cost proportional to what this turn added rather than to the whole history.

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

const policy = createBudgetPolicy({
  budgetTokens: 60_000,   // budget (estimated input tokens)
  keepRecent: 20,          // how many recent messages compaction keeps
  editBeforeCompact: true,  // edit before compacting
  compactEvery: 1,          // compaction hysteresis (turns)
  // summarize: (historyText) => ...,  // compaction only happens if you provide this
});

Structured results

Give run a resultSchema and the model submits its result through a hidden submit_result tool; the framework validates it and attaches it to result.typed — no more guessing JSON out of plain text.

const { result } = await app.run(messages, {
  resultSchema: {
    type: 'object',
    properties: { pass: { type: 'boolean' }, reason: { type: 'string' } },
    required: ['pass', 'reason'],
    additionalProperties: false,
  },
});
console.log(result.typed); // { pass: true, reason: '…' }

The schema can also come from zod (an optional peer): fromZod(z.toJSONSchema(S), S). Validation runs through zod, and the error path goes back to the model verbatim so it can correct itself.

Observability: trace as a first-class citizen

One run == one trace (traceId === runId), built in from turn 0 — not a third-party tracing SDK bolted on. This is the line between Agentia and an agent demo that stops at “it runs”: the four kinds of capability decide what it can do, the trace decides whether you dare to ship it.

• Every step accounted for: each span carries model, input / output / cache tokens, estimated cost, status and error class. The rule is explicit — totalUsage accumulates from llm.turn only, while a capability span's usage is the aggregate of its descendants, never double-counted.
• The exit is one seam: TraceSink { export(trace) } — and the run delivers on both the success and failure paths, with a throwing sink unable to affect the run. Persistence, querying, sampling and redaction are all done outside the seam by composing sinks; the framework does not choose your policy (working code in examples/observability/, write-up in docs/observability.md).
• Cost is controllable: priceOverrides patches the price table; when a model is not in the table the framework emits an explicit usage.unpriced event (it does not silently treat it as zero); see “Hard cost control” below.
• Replayable: traceToMessages(trace) linearises a finished trace back into messages for the model, as the basis for debugging and for “change the prompt and run it again”.
• Exportable: createOtlpExporter({ endpoint }) pushes OTLP and aligns with the OTel GenAI semconv on export (it adds gen_ai.* keys: the run root as invoke_agent, gen_ai.request.model on llm.turn, and score events translated to gen_ai.evaluation.result, while the existing usage.* keys stay); metricsSink() puts metrics through the same seam too (Prometheus text or OTLP metrics), with zero dependencies throughout. Wiring is in “Scenario guide · Put monitoring on a run”.
• Visible locally: agentia dev starts a local inspector panel sharing one renderer with @migor/trace-view — the site Playground uses the same one, so three surfaces run one implementation and cannot drift.

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

const { result } = await app.run(messages);

result.trace.spans;       // the call tree: llm.turn / capability spans / events
result.trace.totalUsage;  // token totals (accumulated from llm.turn only)

// The exit is one seam: persistence / sampling / redaction / metrics are composed outside it; no policy is built in
await createOtlpExporter({ endpoint: 'http://localhost:4318' }).export(result.trace);

Metrics and the tuning report (“which capability is slow / expensive / error-prone”) are in “Ecosystem & observability” below.

Hosting & exports

The server.ts below wires the HTTP host, a SQLite task store and the OTLP exporter together.

import { createServer } from 'node:http';
import { createHttpHandler, SqliteTaskStore, AsyncRunner, createOtlpExporter } from '@migor/agentia';

const runner = new AsyncRunner(app, { store: new SqliteTaskStore('./tasks.db') });
createServer(createHttpHandler(app, { runner })).listen(8080);
// POST /run (sync / SSE)  POST /tasks (async)  GET /tasks/:id (polling)  GET /healthz (probe)

const otlp = createOtlpExporter({ endpoint: 'http://localhost:4318' });
await otlp.export(result.trace);

Models & memory

The engine depends only on the ModelClient structural surface: Anthropic satisfies it natively, and OpenAI-compatible endpoints (DeepSeek and friends) plug in with one line of createOpenAIClient; the memory option hydrates and writes back the blackboard between runs.

import { createOpenAIClient, InMemoryMemoryStore } from '@migor/agentia';

const { result } = await app.run(messages, {
  client: createOpenAIClient({ baseURL: 'https://api.deepseek.com' }),
  model: 'deepseek-chat',
  memory: { store: new InMemoryMemoryStore(), keys: ['profile'] },
});

Stability & streaming

Cancellation, retries and streaming share one per-call options object, carried from the entry point all the way to the model request.

• Cancellation propagation: signal travels all the way to ModelClient.messages.stream (both built-in Anthropic and OpenAI adapters forward it); an interruption does not bubble an exception, and the run closes with stopReason='aborted'. The HTTP host builds in “client disconnect ⇒ abort”, and AsyncRunner.runTimeoutMs aborts an in-flight run when it hits.
• Retries and backoff: on by default (maxAttempts=3, exponential backoff + jitter), and only failures where the attempt produced no text at all are retried — text already streamed cannot be taken back. Each attempt opens its own llm.turn span.
• SSE streaming: POST /run with Accept: text/event-stream emits text.delta / run.end / error frame by frame; without that header it still answers with unary JSON. With backpressure protection: once downstream backlog (res.writableLength) exceeds sseMaxBufferedBytes (8 MiB by default) the stream is closed and the corresponding run is aborted — otherwise one client that connects but never reads would exhaust memory.

const { result } = await app.run(messages, {
  signal: controller.signal,                        // cancellation propagates into in-flight model requests
  retry: { maxAttempts: 3, baseDelayMs: 500 },   // on by default; retry: false turns it off
  onText: (delta) => process.stdout.write(delta),  // streaming text deltas
});

Host hardening

The framework does not implement token / JWT auth, and it does not subscribe to process signals — that belongs to the host or a reverse proxy.

• authenticate intercepts at the entry, before the body is read (including unknown paths, so it never reveals whether a path exists); throwing HttpException answers with its status / body, while any other throw answers 401 with the detail going only to server logs.
• drain({ timeoutMs }): refuse new work → wait for in-flight work to finish → force-close any SSE streams still open at the timeout; unfinished tasks stay in the store and the next start calls resumePending() to continue them (they are not discarded).
• GET /healthz → { ok, inFlight, uptimeMs, draining }: unauthenticated (a probe cannot carry credentials) and still answering 200 while draining; inFlight = in-flight synchronous runs + queued/running async tasks.

const handler = createHttpHandler(app, {
  authenticate: async (req) => {
    if (!verify(req.headers.authorization)) throw new HttpException(401, { error: 'invalid credentials' });
  },
});
createServer(handler).listen(8080);
process.on('SIGTERM', () => handler.drain());  // signal handling belongs to the host

Hard cost control

This is complementary to the long-context policy, not the same thing: the context policy changes the messages before sending (to avoid 400s / premature compaction), whereas this changes the run's outcome after accounting — its purpose is controlling spend.

• maxTotalTokens / maxCostUsd: checked after each turn's accounting; going over closes the run with stopReason='budget_exceeded' (counted as a failure) and records a budget.exceeded event on the run root. The scope is the whole run (sub-agents included).
• Two deliberate semantics: a turn where the model finished naturally is not re-labelled a failure for going over (the task did in fact complete); and on overrun the framework does not execute that turn's tools (so no further side effects are produced).
• toolTimeoutMs: a timeout does not kill the run — that tool_result is recorded as is_error so the model takes another route; maxToolConcurrency caps parallel tools within one turn. ⚠️ A timeout means “we stopped waiting”, not cancellation — AgentTool.run receives no signal. It is the sole arbiter: when it is set, a tool's own timeout (the MCP bridge's timeoutMs) takes no part in the decision.
• priceOverrides: patches the price table — override a built-in model's rates, or price a non-Anthropic endpoint (DeepSeek / self-hosted). It is the precondition for maxCostUsd to work at all: with an unlisted model the cost stays 0 and the guardrail never fires, so the framework says so explicitly via the usage.unpriced event, the model_unpriced_turns_total metric and the onUnpricedModel callback — never silently.

const { result } = await app.run(messages, {
  maxTotalTokens: 200_000,  // cumulative token cap (whichever comes first)
  maxCostUsd: 0.5,         // cumulative cost cap (requires the model to be in the price table)
  toolTimeoutMs: 10_000,     // per-tool timeout → is_error, does not kill the run
  maxToolConcurrency: 4,     // cap on parallel tools within one turn
});

Ecosystem & observability

All three go through existing extension points: an MCP tool is just an AgentTool, metrics are just a TraceSink, and evals are assertions written against a trace.

• MCP: mcpTools(client, { server }) maps a server's tools/list onto menu entries. The connectors ship in the box (createStdioMcpConnector / createStreamableHttpMcpConnector, using only node:child_process + global fetch); the framework does not import the MCP SDK, and the McpClientLike seam remains (the official SDK / a remote server / your own transport all still fit). Characters that are unfriendly to an LLM are normalised to _, and the original name is recorded as the mcp.tool.<menu name> attribute keyed by menu name (one entry per call, so parallel calls do not overwrite each other) for auditing / replay. There is one timeout arbiter: when the engine sets toolTimeoutMs, the bridge's timeoutMs takes no part in the decision (a connector's own timeoutMs covers only the assembly-time handshake and tools/list), and both paths share one verdict and one accounting entry (errorKind='timeout').
• evals: scriptedClient([...]) scripts the model round-trips and defineEval({ app, cases, expect }) writes assertions against the trace — whether a prompt change, a model swap or a new tool caused a regression is answered by assertions rather than by eye. Failing cases carry the full trace.
• Metrics: metricsSink() satisfies TraceSink natively, and all three dimensions are derived from the trace with nothing to instrument — run level, plus capability level (call count, failure count, latency, tokens, cost for each tool / skill / subagent: tools read the tool.output event on the turn, skills / subagents read the capability span) and model level (attributed per model, plus a count of “turns whose cost could not be computed”). Durations come in two flavours: a histogram that aggregates across instances, and exact percentiles within the window; render() produces Prometheus text, createHttpHandler({ metrics }) builds in GET /metrics, and export:'otlp' pushes to an OTel collector (hand-written JSON, zero dependencies). Score-level metrics: attachScore writes a score event onto the run root which aggregates into agentia_score{name,source} (gauge, latest value) and agentia_score_total (counter, number of entries) — eval verdicts / LLM-judge / human labels all take this route; a ready-made Grafana dashboard ships with the repo (examples/observability/grafana-dashboard.json). Note that createHttpHandler({ metrics }) only renders — for the numbers to actually accumulate you must wire the same sink into createApp({ sinks: [metricsSink()] }), otherwise they stay 0 and nothing is reported.
• Tuning report: buildRunReport(trace) turns a trace into a ranking of which capability is slow / expensive / error-prone (mergeRunReports aggregates across runs), and one CLI line agentia report traces.jsonl prints the table (you produce that jsonl yourself: attach a TraceSink that appends JSON lines, or export from FileTaskStore); the agentia dev panel shows the same ranking. Faced with a pile of knobs, this is your basis for deciding which to turn.
• Prompt versioning: new SystemPrompt({ version }) writes the version into the run root as system.version, so a trace can answer “which version of the prompt produced this result”. Multi-tenant quotas: combine middleware (intercept) + TraceSink (accounting) + BudgetGuard (per-call cap).

import { createApp, createStdioMcpConnector, mcpTools, metricsSink, defineEval, scriptedClient } from '@migor/agentia';

// 1) MCP: a server's tools become menu entries (the connector ships in the box; you can also pass any object implementing listTools/callTool)
const mcp = createStdioMcpConnector(['uvx', 'mcp-server-time']);
const tools = await mcpTools(mcp, { server: 'time' });
const app = createApp({ system, providers, tools, sinks: [metricsSink()] });

// 2) evals: scripted round-trips + assertions against the trace
const report = await defineEval({
  name: 'time-flow',
  app: () => app,
  cases: [{ input: 'What time is it in Shanghai?', client: scriptedClient([toolCallTurn, finalTurn]) }],
  expect: (r, { trace }) => { /* assert stopReason / which tools were called / typed */ },
}).run();
if (!report.ok) console.error(report.cases.filter((c) => !c.ok));

// 3) metrics: Prometheus text; expose a route that returns metricsSink().render()

Approval, guardrails & code isolation

For guardrails and code isolation the framework only gives the seam, not a subsystem (the policies differ too much for hard-coding to be right); approval, beyond the gate seam, also has built-in suspend / resume (HITL). Every recipe uses existing extension points only; for the full boundaries see the Known boundaries section and /llms-full.txt.

Approval gate

Middleware can await a human decision before letting a call through — the engine will wait for the tool result. Allow = next(); reject = do not call next() (short-circuit, the side effect never happens); reject and redirect the model = throw (recorded as is_error, run continues). For durable approval that survives a process or restart, use @Tool({ approval: 'required' }): the run suspends as suspended (message history persisted), and POST /tasks/:id/approve resumes execution with that decision — see AsyncRunner.approve and ApprovalDecision in the API reference.

import { createApp } from '@migor/agentia';
import type { CapabilityMiddleware } from '@migor/agentia';

const DANGEROUS = new Set(['send_email', 'deploy', 'delete_records']);

const requireApproval: CapabilityMiddleware = async (call, next) => {
  if (!DANGEROUS.has(call.capability.name)) return next();
  const ok = await askHuman(call.capability.name, call.input); // wait in place (the run stops here)
  if (!ok) throw new Error(`not approved: ${call.capability.name}`); // → is_error, the model reroutes
  return next();                                     // allow
};

createApp({ system, providers, middleware: [requireApproval] });

Content guardrails

Input (wrap app.run; on the HTTP side use createHttpHandler({ authenticate }), which intercepts before the body is read), before a tool call (middleware), and output (wrap the return value, or attach sinks).

const callable = {
  name: app.name,
  async run(msgs, opts) {
    const out = await app.run(redactInput(msgs), opts);   // input guardrail
    if (flagged(out.result.finalText)) throw new Error('output blocked by guardrail'); // output guardrail
    return out;
  },
};

Code execution isolation

The framework never executes model-generated code — @Skill runs a method body you wrote and @Tool runs a function you wrote, so model output only ever becomes text / a tool_result. Isolation is done inside the tool implementation (Docker / a subprocess / a micro-VM, your call) and the framework takes no part in it — the AgentTool.run(input) → output contract keeps isolation entirely within the implementation. The one place it touches the edge: if a tool spawns a subprocess, it must kill it on cancellation (the framework's timeout means “stopped waiting”, not cancellation).

Known boundaries (stated plainly)

What the framework does not guarantee — the basis for deciding whether you can use it. It is a long list (dozens of entries, each one guarded in the repo), and it lives in a single source: docs/usage-guide.md §7, which is written in Chinese. That same text is served verbatim at /llms-full.txt, and the Chinese docs page renders the whole table at build time.

Read it at the source rather than trusting a copy here: docs/usage-guide.md §7 on GitHub · /llms-full.txt. The English summary of the same commitments is under Versioning & stability below.

CLI reference

Install globally with npm i -g @migor/cli and use the agentia command.

Environment variables

Versioning & stability

What 0.x means: version numbers follow SemVer, but during 0.x a minor release may contain breaking changes. There is exactly one rule — a breaking change must leave a trace: the corresponding entry in CHANGELOG.md must carry a dedicated section for it (with a heading containing the migration wording) that spells out what you have to change.

# List every section that asks you to act (this page deliberately hard-codes no count — written numbers rot)
grep -nE '^#{3,4} .*(迁移|破坏性)' CHANGELOG.md

⚠️ Stated plainly: this discipline was tightened over time — an early 0.7.1 (a type-surface change) put the migration step in a block quote at the top of the version entry with no dedicated section. So that command gives a lower bound, not the full set; to read everything, read the whole entry for a release.

The 1.0 bar

All three are checkable, not slogans:

• Every item in docs/spec.md §11 “open items” is either delivered or explicitly struck out (with a written reason why it does not block);
• docs/guards.md §2 “to be guarded” is empty — every declared boundary is held by a machine rather than by someone remembering;
• The public export surface goes three consecutive minors without a breaking change.

Performance order of magnitude

The framework ships five benchmarks (scripts/bench-*.ts). They answer shape questions — which cost is paid under what conditions, and what a different implementation would save — not an SLA.

⚠️ Milliseconds are not a promise: they move with the machine / Node version / load, and copying them as an SLA would be wrong. What stays constant is the shape (how many times larger, how many round-trips, what a given cost is proportional to). The five benchmarks deliberately stay out of CI (timing benchmarks only add noise on CI machines) ⇒ nothing guards these numbers, so if you want them, run them yourself using the “Re-run” column.