A typed, agent-oriented AI SDK for AdonisJS 7, built on Vercel AI SDK Core with AI Gateway and any compatible language-model provider.

The npm badge above is the source of truth for the current version. During 0.x, breaking changes ship only at minor-version boundaries with migration notes.

Install

npm install adonis-ai zod
node ace configure adonis-ai

Configure at least one explicit provider model.

AI_DEFAULT_PROVIDER=openai
OPENAI_API_KEY=
OPENAI_MODEL=

ANTHROPIC_API_KEY=
ANTHROPIC_MODEL=

AI_GATEWAY_API_KEY=
AI_GATEWAY_MODEL=openai/gpt-5

Create an agent

node ace make:ai-agent Assistant

import { BaseAgent } from "adonis-ai";

export default class AssistantAgent extends BaseAgent {
  instructions() {
    return "Be concise.";
  }
}

const response = await new AssistantAgent().prompt("Hello");
console.log(response.text);

Included

• Reusable typed agents and an anonymous agent factory
• Vercel AI Gateway access to its full language-model catalog
• A public adapter for any AI SDK-compatible language model
• Built-in direct OpenAI Responses and Anthropic Messages drivers
• Async-iterable streaming and Adonis-friendly SSE conversion
• Zod 4 structured output and validated application tools
• Provider-neutral image/PDF input and application-owned conversations
• Normalized usage, steps, request IDs, errors, and events
• IoC integration, Ace generators, cancellation, and testing fakes

See the full documentation and playground. Ask questions in Discussions, report bugs through Issues, and report vulnerabilities through private security advisories.

The 0.1 message model keeps string prompts compatible while adding typed text/file parts, opt-in ConversationStore persistence, capability preflight, and redacted attachment observability. See the conversations and files guide.