Agentuity Docs

Use the built-in development UI to test agents, validate schemas, and debug responses

Workbench is a built-in UI for testing your agents during development. It automatically discovers your agents, displays their input/output schemas, and lets you execute them with real inputs.

Enabling Workbench

Add a workbench section to your agentuity.config.ts:

import type { AgentuityConfig } from '@agentuity/cli';
 
export default {
  workbench: {
    route: '/workbench',
    headers: {},
  },
} satisfies AgentuityConfig;

Start the dev server and visit http://localhost:3500/workbench.

Development Only

Workbench is only available in development mode (agentuity dev). It is not included in production builds.

Adding Test Prompts

Export a welcome function from your agent to customize Workbench:

import { createAgent } from '@agentuity/runtime';
import { z } from 'zod';
 
const agent = createAgent('Support Agent', {
  schema: {
    input: z.object({ message: z.string() }),
    output: z.object({ response: z.string() }),
  },
  handler: async (ctx, input) => {
    // Agent logic
    return { response: 'Hello!' };
  },
});
 
export const welcome = () => ({
  welcome: `Welcome to the **Support Agent**.
 
Ask questions about your account, billing, or technical issues.`,
  prompts: [
    {
      data: JSON.stringify({ message: 'How do I reset my password?' }),
      contentType: 'application/json',
    },
    {
      data: JSON.stringify({ message: 'What are your business hours?' }),
      contentType: 'application/json',
    },
  ],
});
 
export default agent;

The welcome field supports Markdown. The prompts array provides quick-test buttons in the UI.

What You See

Workbench displays:

Agent selector: Switch between agents in your project
Input schema: See what fields the agent expects
Output schema: See what the agent returns
Execution metrics: Token usage and response time
Response viewer: Formatted output with copy support

Thread Persistence

Workbench maintains thread state across requests, allowing you to test multi-turn conversations. Each browser tab gets its own thread, and state persists until you close the tab.

Test conversational agents that use thread state:

import { createAgent } from '@agentuity/runtime';
import { z } from 'zod';
 
const agent = createAgent('Chat', {
  schema: {
    input: z.object({ message: z.string() }),
    output: z.object({ response: z.string(), turnCount: z.number() }),
  },
  handler: async (ctx, input) => {
    // Initialize turn count on first request (async)
    if (!(await ctx.thread.state.has('turns'))) {
      await ctx.thread.state.set('turns', 0);
    }
 
    const turns = ((await ctx.thread.state.get<number>('turns')) || 0) + 1;
    await ctx.thread.state.set('turns', turns);
 
    return {
      response: `You said: ${input.message}`,
      turnCount: turns,
    };
  },
});
 
export default agent;

Send multiple requests in Workbench to see the turn count increment.

Custom Route

Serve Workbench at a different path:

import type { AgentuityConfig } from '@agentuity/cli';
 
export default {
  workbench: {
    route: '/dev',
  },
} satisfies AgentuityConfig;

Next Steps

Workbench Configuration: Configuration options and embedding in custom frontends
Creating Agents: Agent patterns and best practices
Local Development: Dev server options

Need Help?

Join our Community for assistance or just to hang with other humans building agents.

Send us an email at hi@agentuity.com if you'd like to get in touch.

Please Follow us on

If you haven't already, please Signup for your free account now and start building your first agent!

Testing with Workbench