Agent workspace

A Lobu agent has two parts:

a workspace template containing prompt files, local skills, and evals
an agent definition in lobu.config.ts containing providers, tools, guardrails, network policy, Nix packages, and chat platform bindings

Project-level lobu.config.ts also owns shared organization wiring such as connections, entity schemas, relationship schemas, connector source files, and behaviors.

lobu.config.ts
agents/
  support/
    IDENTITY.md
    SOUL.md
    USER.md
    skills/internal-api/SKILL.md
    evals/promptfooconfig.yaml

A single-agent project may use dir: ".". Multi-agent projects normally give each agent its own directory.

What belongs where

Concern	Location
Name, role, concise identity	`IDENTITY.md`
Standing instructions, workflows, tone, constraints	`SOUL.md`
Shared user, team, or deployment context	`USER.md`
Reusable procedures and Nix package requirements	`SKILL.md`
Behavioral regression tests	`evals/`
Models, tool policy, guardrails, network, Nix packages, platform bindings	`defineAgent(...)` in `lobu.config.ts`
Connections, auth profiles, entities, relationships, behaviors, connector files	project-level `defineConfig(...)`

Keep operator policy in configuration rather than hiding it inside a prompt or skill.

Define the agent

import { defineAgent, skillFromFile } from "@lobu/cli/config";

const support = defineAgent({
  id: "support",
  name: "Support",
  dir: "./agents/support",
  skills: [
    skillFromFile("./agents/support/skills/internal-api"),
  ],
  providers: [
    { id: "openrouter", model: "anthropic/claude-sonnet-4" },
  ],
  network: { allowed: ["api.example.com"] },
  guardrails: ["secret-scan", "pii-scan"],
  tools: {
    allowed: ["Read", "Grep", "mcp__support__*"],
    denied: ["Bash(rm:*)"],
  },
});

The exact schema is in the lobu.config.ts reference.

Prompt files

`IDENTITY.md`

Keep identity short and concrete.

You are Aria, Acme's customer support agent.
You specialize in billing, account access, and product troubleshooting.

`SOUL.md`

Put durable behavior here:

# Working rules

- Be concise and professional.
- Understand the problem before proposing an action.
- Confirm before cancellations, refunds, or account changes.
- Never invent account data.
- Escalate when the user requests a human.

`USER.md`

Use this for shared context that should enter every turn:

# Deployment context

- Company: Acme
- Default timezone: Europe/London
- Support plan: Enterprise

Do not use USER.md as a substitute for live source data or shared entity memory.

Skills, tools, and guardrails

Skills package reusable procedures and optional Nix package requirements.
Tool policy controls visibility and MCP pre-approval patterns.
Guardrails inspect input, output, and tool calls independently of the prompt.
Network policy controls which domains the worker can reach.

Local skills can request packages and provide instructions, but they cannot grant themselves authority.

See Skills, Tool policy, and Guardrails.

Runtime workspaces

The checked-in directory is a template. At runtime, each user, DM, channel, or task gets its own worker workspace.

New workspaces start from the same agent template.
Files created inside one workspace stay private to that workspace.
Durable knowledge belongs in shared memory.
Inference provider and execution environment are independent choices.

See Concepts and architecture.

Evals

Keep regression tests next to the agent and run them after changes to prompts, skills, model routing, retrieval, tools, or guardrails.

See Evaluations.