Skip to content
Wayland Docs

Build a Custom Agent

An agent is a reusable definition of how a worker behaves: its system prompt, its model, its turn limit, and the tools it may use. The desktop ships a read-only pack of built-in agents and lets you add your own. The engine exposes the same agents through the agent command and the --agent flag.

Open the Agents panel

Section titled “Open the Agents panel”

Go to Settings -> Agents. The panel has two sides: local agents that run on this machine, and remote agents that run elsewhere.

Create a local agent

Section titled “Create a local agent”
  1. In the local agents section, start a new agent in the inline editor.
  2. Give it a name, a one-line description, and the system prompt that defines its role.
  3. Set the model it thinks with and, if you want a cap, its maximum turns.
  4. Choose which tools it may use. Keep this list to what the job needs.
  5. Save.

You can start from a built-in agent and adjust it. The built-in pack itself is read-only, so a copy is yours to change.

Add a remote agent

Section titled “Add a remote agent”

In the remote agents section, register an agent that runs on another host. This is how you bring an agent that lives behind a server endpoint into the same picture as your local ones.

The same from the CLI

Section titled “The same from the CLI”

The engine has parity with the panel:

Terminal window
wayland-core agent create my-reviewer --inherit-from architect --description "Reviews PRs"
wayland-core agent list --builtins
wayland-core agent show my-reviewer
wayland-core agent edit my-reviewer
wayland-core agent delete my-reviewer --yes

User agents are stored as TOML files under ~/.wayland/agents/. Built-ins cannot be deleted. To use a built-in persona for a single run, pass --agent <name>, and run wayland-core --list-agents to see them all.

Next

Section titled “Next”