@adonis-agora/agent weekly downloads statistics

@adonis-agora/agent

Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.

The package is two things layered on top of each other:

• A framework-agnostic agent loop — runAgentLoop(deps, input, hooks) drives one model → tools → model turn against a set of SPIs (model / store / quota / roles / sink / runner / governance). The hooks seam (step / awaitApproval / openSink / runAgent) lets the same loop body run in-process or as a replay-safe durable workflow (via @adonis-agora/durable, optional peer). • An AdonisJS integration shell — a service provider, defineConfig, HTTP routes (/agent/*, /agent/governance/*, /agent/attachments), Lucid-backed stores, tool discovery from app/agent_tools, RAG (pgvector or Qdrant retrievers, plus PageIndex-style tree navigation for long documents), a governed read-only SQL tool, and a React chat hook.

read tools auto-execute, action tools gate on human approval (HITL), and agent tools delegate to another named agent.

Component registries and server rendering

Tools support a present hook in both functional and decorated class forms. Register custom components per app, share React renderers between web screens and static exports, and generate paginated PNG/PDF tables and charts for your own delivery adapters.

See the component rendering guide for complete examples, schemas, text fallbacks, and capture configuration.

Generative UI sandbox in React Native

@adonis-agora/agent/react-native/genui draws the sandbox component (ui__sandbox) in a hardened react-native-webview — the web iframe's document and CSP, the same checked agent.send bridge — and re-exports the React Native-safe genui provider and components (import them from here in an app, not from /react/genui). Install react-native-webview (an optional peer), then:

See Sandbox in React Native.

Install

configure registers the provider, wires an Assembler init hook that generates the typed app/agent_tools barrel (falls back to a runtime scan if absent), publishes config/agent.ts, and publishes the migrations — the base agent tables, a pgvector RAG-chunk table, and the tree-navigation tables (delete whichever you don't use, e.g. the pgvector migration if you retrieve via Qdrant instead, or the trees migration if you don't navigate long documents; run node ace migration:run for the rest).

Only ai (or a hand-rolled ModelProvider) and a model factory are strictly required. Everything else is an optional peer, imported lazily only when configured:

| Peer | Needed for |

| ai (^7.0.0) | aiSdkModel — the Vercel AI SDK v7 adapter (@adonis-agora/agent/ai-sdk) | | @adonisjs/lucid (^22.4.0) | stores.lucid(), pricing, governance read-model, the data tool's db | | @adonisjs/redis (^9.2.0) | tokenSinks.redis() — multi-replica SSE token streaming | | @adonis-agora/durable (^0.8.0) | durable: true — replay-safe durable runs (@adonis-agora/agent/durable) | | @adonis-agora/authz (^0.4.0) | AuthzActorResolver / AuthzToolAuthorizer (@adonis-agora/agent/authz) | | @adonis-agora/telescope (^0.4.0) | the Telescope watcher extension (@adonis-agora/agent/telescope) | | @qdrant/js-client-rest (^1.11.0) | retrievers.qdrant({...}) | | node-sql-parser (^5.3.0) | the governed dataTool (@adonis-agora/agent/data) | | react (^18 / ^19), @ai-sdk/react and ai | AgentProvider / useAgentChat (@adonis-agora/agent/react) |

Configure

Only model is required — pick a store by name (omit for the in-memory, single-process store):

Pricing (costUsd on each turn) and the /agent/governance/* read routes both default to mirroring store when it's stores.lucid() (same connection, table auto-created) — override with pricingStore / governanceQueries, or false to disable. sink defaults to the in-process token sink; pass tokenSinks.redis({...}) so any pod can serve any run's SSE stream.

Use

Chat — the provider mounts the HTTP API for you

There's no controller to write: once configured, the provider itself mounts POST /agent/chat (starts a run and SSE-pipes the token stream), GET /agent/chat/:runId/stream (re-attach), thread CRUD, approve/reject for HITL action tools, quota, and — when governanceQueries is set — the /agent/governance/* read routes. Every route resolves the actor itself (401 on failure); a threadId passed to chat must belong to the caller.

Drive it from React with @adonis-agora/agent/react — the full headless layer (history, resume, a message queue, approvals, attachments, threads), with the session cookie and shield's CSRF token already wired:

The hooks ship inside Agora. Its protocol remains compatible with Aviary, but installation and releases are independent. Without React, use the framework-free stream client:

Write a governed tool

Tools are auto-discovered from app/agent_tools. ReadTool auto-executes; ActionTool requires human approval before it runs:

An ActionTool writes somewhere, and that write and the checkpoint recording it are two writes: a worker that dies between them re-runs the tool on recovery. ctx.idempotencyKey (:) is the same for every execution of one call — pass it on as the downstream idempotency key (a provider's Idempotency-Key, a unique column, the id of a workflow the tool starts) so the second attempt lands on the first.

Governed read-only SQL

@adonis-agora/agent/data ships dataTool — a fail-closed SQL tool: it requires an explicit, role-based table allowlist, rewrites in an optional per-row tenant scope (off the calling actor's tenantRef), injects a row-count LIMIT, and truncates oversized results before they hit the model's context. Register it as a static tool in config/agent.ts (defineConfig({ tools: [dataTool({...})] })) or export it from an app/agent_tools/ module:

Guardrails — PII, secrets, prompt injection, tool poisoning

@adonis-agora/agent/guardrails puts detectors and a rule engine on the loop's processor seams, which config/agent.ts now takes as inputProcessors / outputProcessors:…

Description from the npm listing.