Write your first plug

In this tutorial you write a small plug, put it in a blaise.yml, and see the file it creates when a session starts. It takes about fifteen minutes. You need what the first tutorial set up: a local agent and a runner authorized on this machine, and Bun installed.

1. Create a project

mkdir stamp-demo
cd stamp-demo
bun init -y
bun add @blaiseagent/runner zod

2. Write the plug

Create plugs/stamp.ts:

import { z } from "zod";
import { definePlug } from "@blaiseagent/runner";

export default definePlug({
  name: "acme/stamp",
  inputs: z.object({ message: z.string() }),

  async onSession(ctx, next) {
    // Write a file in the agent's working directory before the agent starts.
    const file = `${ctx.agent.cwd}/stamp.txt`;
    await ctx.host.fs.promises.writeFile(file, `${ctx.inputs.message} (${ctx.session.id})\n`);

    await next();
  },
});

definePlug describes a plug. This one takes one input, message, and has one handler, onSession. The handler runs when a session starts. It writes a file in the agent's working directory, and then calls next(), which runs everything after it, the agent included.

3. Add it to blaise.yml

Create blaise.yml next to package.json:

version: 1
setup:
  - use: ./plugs/stamp.ts
    with:
      message: hello from my first plug

4. Start the runner

blaise-agent listen

The runner loads the plug and checks with: against the plug's inputs before it waits for sessions. Remove the message line and start it again to see that check refuse to start; put the line back before you go on.

5. Start a session

In the Blaise dashboard, open your agent and start a session with any prompt. When the agent has answered, look in the directory where you started the runner:

cat stamp.txt

hello from my first plug (<the id of the session>)

The plug ran before the agent started, and wrote the file.

What you did

You wrote a module with definePlug, pointed blaise.yml at it, and the runner ran every session through it. Where to go next:

• Test a plug without a server.
• Write a local plug that changes the agent's messages.
• How plugs wrap a session