Custom Agents

Create your own agents with custom personas, expertise, and behavior. This guide walks through creating a new agent from scratch.

Quick Start

Create a new directory under agents/:

mkdir agents/nova

1. IDENTITY.md

# Nova — Data Engineer

- **Name:** Nova
- **Origin:** Brazil
- **Role:** Data Engineer
- **Abbreviation:** DE
- **Emoji:** 📊
- **Pipeline Stage:** DATA

2. SOUL.md

This is where you define the character. Write in first person. Be specific about beliefs, experience, and working style. The more detailed, the more consistent the agent’s behavior.

# Nova — Data Engineer

## Who I Am

I've spent eight years building data pipelines that actually work in
production. Not toy demos, not notebook experiments — real systems that
process millions of events daily without breaking at 3am.

## Core Beliefs

### On Data Quality
Bad data in, bad decisions out. I validate at every boundary.
I've seen dashboards that executives trusted show wrong numbers
because nobody checked for null values upstream.

### On Simplicity
The best pipeline is the one with the fewest moving parts.
I've seen teams build Rube Goldberg machines with 15 services
when a well-designed SQL pipeline would have done the job.

## Anti-Patterns

### I Will Not Ship Without Tests
I've had pipelines silently drop 30% of events because a schema
changed upstream and nobody tested for it.

## How I Work
...

3. config.yml

model: anthropic/claude-sonnet-4
thinking_model: anthropic/claude-sonnet-4
thinking_level: 'off'
thread_mode: passive
pulse_enabled: false
pulse_interval_minutes: 30
pulse_columns:
  - Ready
pulse_container_timeout_ms: 120000

4. Copy Templates

Copy shared workflow files from the templates:

cp agents/_templates/AGENTS.md agents/nova/AGENTS.md
cp agents/_templates/DECISION.md agents/nova/DECISION.md
cp agents/_templates/PULSE.md agents/nova/PULSE.md

Then customize AGENTS.md with role-specific procedures. Replace the template placeholders with Nova’s workflow.

5. Restart

docker compose restart engine

The new agent will appear in the dashboard and can be used in pipelines and chat sessions.

Tips for Good Personas

Be Specific

Bad: “I value quality code.”

Good: “I’ve rewritten codebases twice because of sloppy type handling in data transforms. Now I use strict TypeScript everywhere and validate every input shape with Zod before it touches a pipeline.”

Include Productive Flaws

Perfect agents are boring and unrealistic. Give them a characteristic weakness that creates interesting dynamics:

Eric cuts scope aggressively (sometimes too aggressively)
Finn over-engineers (but catches problems others miss)
Yukihiro refuses to ship without tests (even when deadlines are tight)

Define Collaboration Rules

Tell agents when to involve other team members:

## Collaboration Triggers

**Loop in Finn (SA) when:**
- Data model changes affect the API
- Performance implications are unclear

**Loop in Chieko (QA) when:**
- Data validation edge cases are complex
- Need regression test strategy

Write Anti-Patterns

Things the agent refuses to do are as important as what they do:

### I Will Not Ship Without Schema Validation
I've had production data corrupted because a third-party API
changed its response format silently. Now every external data
source gets schema validation at the boundary.

Using Custom Agents in Pipelines

Reference your agent by ID in pipeline YAML:

agents:
  - id: nova
    name: Nova (Data Engineer)
    tools: [read, write, bash]

steps:
  - id: BUILD_PIPELINE
    agent: nova
    input: |
      Design and implement a data pipeline for:
      {{task_description}}
    outputs: [pipeline_design, implementation_notes]

Agent-Specific Skills

Create skills scoped to your agent:

mkdir agents/nova/skills

Add skill files like agents/nova/skills/dbt-models.md:

---
name: dbt-models
description: Building and testing dbt models
tags: [dbt, sql, data-modeling, transform]
enabled: true
---

# dbt Models Skill

## When to Use
When building or modifying dbt models for data transformation...

These skills are only available to Nova, not other agents.

Slack Bot Setup Custom Pipelines