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:
- Read what you gave it. It reads each skill, tool or MCP server you link to, and prefers tools that already exist.
- 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.
- 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.
- 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.
- 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-toolsconnectors, 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_Yorkvalet 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
- 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
- Connectors: configure the services an agent can use.
- Skill library: manage instructions shared by hosted agents.