---
sidebar_position: 2
title: 2. Your first agent
pagination_prev: get-started/install
pagination_next: get-started/run-locally
---

# Scaffold your first agent

An **Agent** is a deployed automation. Scaffold one with the CLI with the `zibby agent` CLI:

```bash
zibby agent new my-agent
# zibby agent new my-agent   # alias — identical
```

This creates:

```
.zibby/workflows/my-agent/
├── graph.mjs         # the workflow definition (entry point)
├── nodes/
│   └── example.mjs   # a sample node
├── package.json      # agent's own deps (each agent is a self-contained npm project)
└── workflow.json     # manifest (workflow name, entry class)
```

If `.zibby/workflows/` doesn't exist yet, the scaffold creates it. If you have a `.zibby.config.mjs` with a custom `paths.workflows`, the scaffold respects it.

The first time you run this in a fresh directory, you'll be asked where to keep agents (default: `.zibby/workflows`). The CLI also runs `npm install` inside the new agent folder so deps are ready.

## What's in graph.mjs

```js
import { z } from '@zibby/core';
import { WorkflowAgent, WorkflowGraph } from '@zibby/agent-workflow';
import { exampleNode } from './nodes/example.mjs';

export class MyPipelineWorkflow extends WorkflowAgent {
  buildGraph() {
    const graph = new WorkflowGraph();

    graph.addNode('example', {
      prompt: exampleNode.prompt,
      outputSchema: z.object({
        summary: z.string(),
        status: z.enum(['ok', 'warn', 'error']),
      }),
      agent: 'cursor',          // per-node agent override
    });

    graph.setEntryPoint('example');
    return graph;
  }
}
```

The shape is:

- `graph.addNode(name, config)` — register a node. `prompt` becomes the agent's input; `outputSchema` (Zod) defines the contract for what comes back.
- `graph.addEdge(from, to)` — wire two nodes together.
- `graph.addConditionalEdges(from, fn)` — branch on state.
- `graph.setEntryPoint(name)` — first node to run.

## Picking the agent

Each node can specify its own agent via `agent: 'cursor' | 'claude' | 'codex' | 'gemini' | 'assistant'`. If you omit it, the agent falls back to the project default (set in `.zibby.config.mjs` or `AGENT_TYPE` env var).

→ Next: [Run it locally](./run-locally)