Waymaker
Agents

Creating Your First Agent

Learn about Creating Your First Agent in WaymakerOS.

ScaffoldDeployInvoke

This walks you from an empty folder to a deployed agent that remembers.

1. Scaffold the project

npm create waymaker-agent my-agent
cd my-agent
npm install

You get a working project with a waymaker.config.ts that declares type: "agent" — that declaration is what tells Waymaker to build this as an Agent rather than an App.

2. Write the agent

Your agent lives in src/agent.ts and exports two optional handlers:

import { defineAgent } from '@waymakeros/agent-runtime'

export default defineAgent({
  // Runs when someone invokes this agent
  async onRequest(request, ctx) {
    const count = (await ctx.state.get<number>('visits')) ?? 0
    await ctx.state.put('visits', count + 1)

    return new Response(`Hello ${ctx.tenantId} — visit #${count + 1}`)
  },

  // Runs when a schedule you set elapses
  async onAlarm(ctx) {
    const pending = await ctx.state.get('pending')
    // ...do the follow-up work
  }
})

Two things worth noticing:

  • ctx.state persists. That counter is still there tomorrow. Restarts and redeploys don't clear it.
  • ctx.tenantId is the id this call was addressed to. The same code serves every tenant; each gets its own separate memory.

3. Deploy

Push to your connected repository, and Waymaker builds and deploys the agent automatically — the same pipeline as Apps.

git push

Or create it from the Agents section of Host and connect the repository there.

4. Invoke it

waymaker agents invoke my-agent --id acme
waymaker agents invoke my-agent --id globex

Run those twice each. Acme counts 1, 2 — Globex counts 1, 2, entirely separately. That's per-tenant memory working.

You can also invoke an agent over HTTP, or from another agent, an Ambassador, or your app's code.

What you get in ctx

Everything an Ambassador has, plus memory and schedules:

ctx.What it's for
stateDurable memory for this tenant — get, put, delete, list
scheduleWake this agent later — at, in, cancel, next
aiGenerate text and decisions (your credits, or your own key)
tablesYour Commander tables — query, insert, update, delete
postgresYour app's database
commanderGoals, projects, and team from your organisation
user / workspaceWho and where this invocation belongs to
tenantId / agentIdThe instance being addressed, and this agent's id

Watching it run

Every invocation is recorded. Open the agent in Host to see its recent runs, or check the Monitor section for volume and error rates across everything you've deployed.

Next Steps