ai-agent
Write, wire and test an in-process AI agent with @guren/plugin-ai (an Agent class that calls a language model and reaches the app through its .agent() routes). Use when the user asks to "add an AI fea
SKILL.mdpackages/cli/templates/agent/core/skills/ai-agent/SKILL.md
GitHubAI Agent Skill
An in-process agent is a class under app/Ai/Agents that calls a model configured in config/ai.ts. It reaches the application only through appTools(), which turns the app's .agent() routes into model tools and runs every call through the same pipeline as the MCP endpoint: scopes, the route's validation and policies, approvals, and the audit trail. Nothing about a route is written twice.
Setup (once per app)
bunx guren add ai # config/ai.ts, the key in config/env.ts, aiPlugin(), conversation tables
bunx guren add ai --provider openai # or gateway
It needs config/env.ts. The key is optional: the app boots without it and the first prompt fails. Do not remove the if (!env.ANTHROPIC_API_KEY) throw guard in config/ai.ts; without a key the provider SDK reads process.env and sends a blank key.
Writing an agent
bunx guren make:ai-agent TicketDigest --tools tickets_index --output --test
--tools fails if no route derives a name, so expose the route first (the agent-interface skill). Then check the generated class:
import { Agent, Output } from '@guren/plugin-ai'
import { z } from 'zod'
export class TicketDigest extends Agent<typeof TicketDigest.scopes> {
static override agentName = 'ticket-digest'
static override scopes = ['tool:tickets_index'] as const
instructions = 'You write a short digest of the open support tickets for an operator.'
output = Output.object({ schema: z.object({ summary: z.string() }) })
override tools() {
return this.appTools(['tickets_index'])
}
}
Rules:
- Keep
static agentNamepinned. Fakes, audit lines, queued runs and stored conversations key on it; the class-name default changes under a minifier. - Scopes are
tool:<name>entries, one per tool.tools:read,tools:*andtools:<prefix>.*grow silently as routes gain.agent(), and a prefix only matches dotted names. - Keep
Agent<typeof X.scopes>withscopes ... as const. That type parameter is what makes an ungrantedappTools()name a compile error. Runbunx guren codegenso.guren/agents.gen.tstypes the names. - Tool names must match
[A-Za-z0-9_-]{1,64}. Anthropic and OpenAI rejecttickets.index; setagent: { toolName: 'tickets_index' }on the route. - Prefer
appTools()over a localtool(). A local tool runs with its closure's authority: no scope, policy, approval or audit applies. Use one only for work no route does, and never for a Model write a route already performs.
Calling it
const user = await this.auth.userOrFail<{ id: number }>() // a type argument with id; the default Authenticatable does not fit as()
const response = await this.make('ai').agent(TicketDigest).as(user).prompt('...')
response.output // typed from `output`; response.text, steps, usage, finishReason
as(user)makes every tool call a request as that user, so the route's policies decide.as(null)allows read-only tools only and fails atas()otherwise.- Tool results are untrusted model input (a ticket body can carry instructions). The consequential action must be a gated route, never a local tool.
- Conversations:
prompt(input, { conversation: true })starts one and returnsconversationId;.continue(id)resumes it. Nothing is stored without asking. The tables hold transcripts as the model saw them: sensitive data. - Chat:
.stream(message, { conversation: conversation ?? true, signal: this.request.raw.signal })aftervalidateBody(ChatTurnSchema), withcreateChatTransport()from@guren/plugin-ai/clientin the page. An agent withoutputcannot stream. - Background:
.queue(input)needsaiPlugin({ agents: [TicketDigest] }), a queue binding andbunx guren queue:work; listen forAgentResponded. A run is attempted once..broadcast(input, channel)streams the same run to a broadcast channel asAGENT_CHUNK_EVENT; make that channel private, since publishing is not authorized.
Test it with the fake, first
using ai = app.fakeAi() // app = await TestApp.fromApp(realApp)
ai.respond(TicketDigest, [
{ toolCalls: [{ name: 'tickets_index', input: { status: 'open' } }], then: { output: { summary: 'One fire.' } } },
])
// drive the route or call the agent, then:
ai.assertPrompted(TicketDigest, (input) => input.includes('digest'))
expect(ai.calls(TicketDigest)[0]!.toolCalls[0]?.output).toBeDefined() // the real route's answer
- Only the model is scripted. Tool calls hit the real routes, so the test proves scopes, policies and approvals are wired. Never stub the tools.
- An unscripted prompt fails the test when
aiis disposed, naming the agent, even if the route turned the error into a 500. - Mutation-check: bind the agent
as(null)or drop the scope and confirm the test fails.
A passing fake test proves wiring, not answer quality. Do not claim an agent "works well" from fake tests alone, and never call a real provider from bun test or CI. Answer quality is measured by an eval: defineEval() in tests/evals/<flow>.eval.ts and bunx guren ai:eval <flow>, which calls the real model, costs money, and is never part of guren check or guren gate. Run it when asked, with --dry-run first.
Full guide: docs/en/guides/ai-agents.md (or docs/ja/guides/ai-agents.md) in the Guren framework repo. Routing reference: __RULES_DIR__/routes-codegen.md.