Build

Agents

On this page

What an agent is

An agent is an AI worker that Valet runs for you. It keeps working after your chat with your coding agent ends: it answers questions in Slack, handles email, or posts a report every morning. By default it sleeps when no work is in progress, and the next message or scheduled run wakes it. Each agent also has its own address, where members chat with it.

You describe an agent in a folder:

support-bot/
  SOUL.md              Who the agent is and how it works
  skills/
    refunds/SKILL.md   Instructions for one task
  channels/
    inbox.md           Instructions for one channel
  valet.yaml           Name, description, connectors and channels
  • SOUL.md holds the agent's instructions in plain language.
  • A skill holds instructions for one task. The agent reads it only when the task comes up.
  • A channel is how work reaches the agent, such as a Slack message or a schedule. A file in channels/ holds instructions for one channel.
  • valet.yaml names the agent and lists the connectors and channels it needs.

Create an agent

Ask your agent:

Build a Valet agent called support-bot that answers billing questions
in Slack, and deploy it.

Your agent writes the folder, creates the agent, then publishes the files:

create_service
{ "kind": "agent", "name": "support-bot" }
publish_agent
{
  "name": "support-bot",
  "files": [
    { "path": "valet.yaml", "content": "name: support-bot\ndescription: Answers billing questions in Slack.\n" },
    { "path": "SOUL.md", "content": "You answer billing questions for Acme's support team.\n…" }
  ]
}

Over MCP, create_service creates an empty agent. publish_agent deploys it and waits for deployment to finish. An agent that can run git publishes from a Git push instead of files; see Publish with Git. Chat with the agent in the dashboard. With the CLI, valet new writes starter files, valet agents create creates the agent from the current folder and deploys it with Git, and valet console opens a chat with it. It needs Git 2.32 or later unless it creates the agent from the catalog or a Git URL with --from.

Design it with your coding agent

Ask your agent:

Help me design a Valet agent that triages new GitHub issues every
morning. Ask me what you need first.

A good design session runs in this order:

  1. Read what you gave it. It reads each skill, tool or MCP server you link to, and prefers tools that already exist.
  2. Interview. It confirms what wakes the agent, such as a schedule, a webhook or a chat message, then asks only what it needs: the decision points, where results go, edge cases and limits. Seven questions at most.
  3. Find the tools. Valet's connector catalog first, then your organization's connectors, then public skills and MCP servers. A step with no tool stays manual.
  4. Show the plan and wait. What it will write, what it will set up on Valet, and what you must do yourself: each secret to enter and where to get it, and each step outside Valet. It builds nothing until you agree.
  5. Build and check. It writes the files below, creates the agent, and watches its logs while you trigger each channel.

To turn work you just did into an agent, ask your agent:

Save this session as a Valet agent.

It reads the session's prompts, tool calls and your corrections. The tool calls become the agent's workflow, what worked becomes its Always rules, and your corrections become its Never rules. Values that belong to one person or account become placeholders.

Write the files

valet new <name> writes starter files. Deployed files are read-only while the agent runs, and files the agent writes don't survive a deploy.

SOUL.md

SOUL.md is the agent's instructions. Give it a specific purpose, a workflow that names real tools, and guardrails:

# Issue Triage

## Purpose

Every weekday at 9:00, reads new issues in acme/web, labels each one,
and posts a summary to #eng-triage.

## Workflow

1. List issues opened since the last run with the github connector.
2. Label each one bug, feature or question.
3. Post the summary to #eng-triage.

## Guardrails

### Always
- Link each issue in the summary.

### Never
- Close or assign an issue.

"Watches acme/web for new issues and posts a summary" is a purpose; "processes data" is not. Call a command connector by its connector name, the program Valet puts on the agent's PATH: a connector named agentmail is run as agentmail inboxes list, never through the package it wraps, which would skip its secrets. An agent woken by webhooks gets a scope rule: its work is limited to what the payload's identifiers name.

valet.yaml

valet.yaml needs four fields:

name: issue-triage
display_name: Issue Triage
description: Labels new GitHub issues and posts a morning summary.
category: developer-tools

connectors, channels and skills entries name catalog items, such as catalog: github; a custom connector or channel is created and attached separately. cron, heartbeat and mcp channels can be declared inline, and the deploy creates them:

channels:
  - type: cron
    schedule: "weekdays at 9am"
    timezone: America/New_York

valet manifests validate checks the file; see Check a manifest.

Channel files

channels/<name>.md tells the agent what to do when that channel fires. Write it as direct instructions. A webhook's payload arrives right after the file in the same message, so start each webhook channel file with:

The JSON webhook payload is appended directly after these instructions
in the user message. Parse it inline — do not fetch, list, or search
for the payload elsewhere. Do NOT use tools to read the payload.

Then say what happened, which payload fields identify it, a scope limited to those identifiers, and the steps. Publish the agent again after you change a channel file.

AGENTS.md

AGENTS.md tells a person or a coding agent how to set the agent up again. Write it last, in plain words, and never put a secret in it:

## Setup

### Connectors
- **github**: reads issues in acme/web to label them

### Channels
- **morning** (cron): weekdays at 9:00, starts the triage

### Secrets
- **GITHUB_TOKEN**: a GitHub token with issues read and write

### External setup
Steps outside Valet, plainly enough for someone new to follow.

Leave out a section that doesn't apply.

Channels

Every agent has a console channel: the chat in the dashboard and in valet console. Add others to wake the agent in other ways, such as a schedule:

create_channel
{
  "name": "support-bot",
  "channel": "morning-summary",
  "channel_kind": "cron",
  "schedule": "weekdays at 9:00am",
  "timezone": "America/New_York"
}

When a channel fires, the agent follows the instructions in channels/<name>.md, here channels/morning-summary.md.

Webhook

What wakes the agent
A request from another service
Setup
Signed with a secret by default

Cron

What wakes the agent
A schedule, such as weekdays at 9:00
Setup
None

Heartbeat

What wakes the agent
A fixed interval, from 30 seconds to 24 hours
Setup
None

MCP

What wakes the agent
Another AI tool calling the agent as a tool
Setup
A token for each caller, from valet channels token mint

Slack

What wakes the agent
A message or an @mention
Setup
Someone connects Slack to the organization once; each agent then gets its own Slack app

Email

What wakes the agent
Mail to an address such as support@acme.valet.run
Setup
None

Telegram

What wakes the agent
A message to the agent in Telegram
Setup
Each person connects by opening the link the channel prints

create_channel makes cron, heartbeat, webhook and MCP channels. Slack and Telegram need a browser, so they start in the dashboard or the CLI.

Agents aren't the only ones with channels. An app takes webhook, cron and heartbeat channels too; see Webhooks and schedules.

What an agent can use

A connector gives the agent a service's tools, such as HubSpot or Google Drive. Valet adds the credential on each call, so the agent never holds it.

attach_connector
{ "name": "support-bot", "connector": "hubspot" }

When you deploy, Valet attaches each connector and channel valet.yaml names that the organization already has. A manually detached connector returns on the next deploy if valet.yaml still names it. If valet.yaml names a connector or channel the organization doesn't have, or a skill that doesn't exist, the deploy fails and lists what to set up. valet deploy --allow-unsatisfied deploys anyway, and the agent runs without the missing pieces until you add them. See Connectors.

An env var is a named setting. Its value is secret by default: the agent's connectors and channels can use it, but the agent never sees it. Store a value as plain, with plain_vars in set_env_vars or --plain in the CLI, when the agent should read it directly, such as a region. To set a secret over MCP, name it in secret_names. You enter the value on a page in your dashboard.

Skills from your organization's library provide instructions for specific tasks. Attach one a teammate published:

attach_skill
{ "name": "support-bot", "skill": "org:ticket-triage" }

A skill in the agent's own skills/ folder ships with the agent. An attached skill comes from the library and follows its new releases; there is no pin. See Skills.

The agent has memory: tools to remember, recall and forget facts. A memory belongs to one conversation, such as a Slack channel, or to the whole agent. Up to 5 pinned memories reach the agent on every turn. Each agent holds up to 1,000 memories of up to 4 KB each. list_memories and set_memory list and set them, as does valet memories.

Agents run on the claude-sonnet-5 model unless you choose another with valet ps scale agent=<model>.

Changing its own instructions

An agent can propose changes to its own SOUL.md, its own skills and its channel files. Valet's code checks each change before it takes effect:

  • It can't change valet.yaml, so it can't add connectors or channels.
  • It can't change a skill attached from elsewhere.
  • It can make at most 10 changes an hour.
  • If its change conflicts with a person's edit, the person's edit wins.
  • Each change becomes a new release. A failed build leaves the current release running.

Valet's instructions also tell the agent never to change itself because something it read asked it to.

Its address

Every agent serves a chat page at https://<agent>.<org>.valet.run. get_service, or valet agents access <name> with no mode, prints the address. Each visitor sees only their own conversations.

A new agent is private: members open it after they sign in. Like an artifact, an agent can be put behind a password, made public, or shared with one person by email:

set_service_access
{ "name": "support-bot", "kind": "agent", "mode": "public", "reason": "Customers chat with the support bot." }

share_service
{ "name": "support-bot", "kind": "agent", "emails": ["alice@example.com"] }

Opening an agent to people outside your organization may not be available yet. If it isn't, Valet refuses and says so.

A visitor who opens the agent can use what its connectors let it do. Someone outside the organization can't make the agent change its own instructions or schedules, and can't make it forget or remember things for the whole organization.

Who can reach it

Only members of your organization can use the console or the chat page at the agent's address, https://<agent>.<org>.valet.run. On every other channel, anyone the channel reaches can talk to the agent:

  • Slack: anyone in the workspace who can message the agent's bot.
  • Email: anyone who sends mail to its address, unless the channel's sender policy limits it to an allowlist or to organization members.
  • Webhook: anyone with the URL and its signing secret.
  • MCP: anyone holding a token you minted, and organization members who sign in where MCP sign-in is set up.

Releases

Each publish, with publish_agent or valet deploy, creates a numbered release, v1, v2 and so on, and makes it live. list_releases or valet releases support-bot lists them. Changing a connector or an env var, and each change the agent makes to itself, also creates a release. The CLI has no rollback command. Ask your agent, or call rollback_service with a version from list_releases: it publishes the earlier files again as a new release.

A blocking release policy can refuse a release. The agent keeps running its current release. See Release policies to review findings in the dashboard's Releases tab.

Run and watch it

list_sessions
{ "name": "support-bot" }

get_logs
{ "name": "support-bot", "kind": "agent" }

scale_service
{ "name": "support-bot", "count": 0 }

restart_service
{ "name": "support-bot" }

These list the agent's conversations, read its logs, pause it, and restart it.

An agent runs on economy-1x by default, which sleeps after 30 minutes without work. standard-1x is the same machine and never sleeps. Changing size restarts the agent:

scale_service
{ "name": "support-bot", "size": "standard-1x" }

get_session, or valet sessions <id>, shows one conversation's transcript. Over MCP, transcripts and logs come back with credentials removed, on a best-effort basis; see What reads return. Scaling the agent to 1 resumes it. A restart cuts off conversations in progress.

To watch a new channel work, follow the logs while you trigger it:

No MCP tool does this. Use the CLI.

A healthy run takes few turns, pairs each mcp_call_tool_start with an mcp_call_tool_done, and ends with dispatch_complete. Many turns that use only built-in tools mean the agent is looping. A run with no dispatch_complete stalled.

Next steps