Guides
Server logic
Call agents, runs, automations and models from your own routes with actor-bound services.
Use actor-bound services in your own routes to list records, start runs, or answer approvals. Services use the signed-in user and selected workspace, so you keep the API's access checks without making an HTTP request back to your app.
Using Services in Nuxt
useAgentic(event) is auto-imported in server routes:
export default defineEventHandler(async (event) => {
const { models } = await useAgentic(event)
return models.customer.list({ filter: { plan: 'pro' }, columns: ['name', 'email'] })
})
useAgentic(event) reads the session cookie and the X-Agentic-Workspace header, exactly like
the API. Requests without a session fail with 401. Services are typed from your models, agents,
and features.
useAgenticAuth(env) returns the better-auth instance, for example to read the session. See
Server Utilities.
Using Services in Void
Import your definition and pass it the request and bindings:
import { defineHandler } from 'void'
import agentic from '../../src/agentic'
export const GET = defineHandler(async (context) => {
const { models } = await agentic.services(context.req.raw, context.env)
return models.customer.list({ filter: { plan: 'pro' } })
})
What Services Offer
| Service | Operations |
|---|---|
models.<name> | list, get, create, update, delete, as allowed by the model's access |
agents | list, get, code(slug), create, update, delete |
runs | start(agentId, input), get, cancel, runtimes |
automations | CRUD, start, cancel, resume, deliverEvent, folders, runs, templates |
approvals | The approvals inbox; answer(approvalId, approve) approves or rejects a call |
workspaces | session, list, create, get, update, setRole, removeMember |
prompt | options, plan, execute, cancel |
See Services for inputs and results. To add your own routes to the Agentic API, with access checks and OpenAPI, write a feature.
Starting Automations from Your Code
Deliver an app event, and every matching automation starts:
const { automations } = await useAgentic(event)
await automations.deliverEvent({
event: 'order.created',
id: String(order.id),
payload: { order },
})
This starts the signed-in user's active order.created automations in the current workspace.
Other members' automations do not start. The id (up to 200 characters) makes delivery
idempotent: sending the same event again does not start another run.
Services always act as the signed-in person. For work without a request, use an automation with
a schedule trigger or a webhook.