---
title: Agents
description: An agent is a markdown file that the session harness runs; the manifest only governs its access.
---

An agent is a markdown file that defines how the harness acts in a
[session](/docs/work/sessions). This page covers agent files, skills, and
how a session picks an agent.

## A harness runs every session

A session uses either the default runtime or the experimental runtime.
[Harnesses](/docs/work/harnesses) lists how a project selects one and what
each one supports.

Both read the project's agents from `agents/` and its skills from `skills/`.
The default runtime also reads the files only it uses from `harnesses/opencode/`. The experimental runtime
reads its own from `harnesses/pi/`.

Projects created before 2026-09 keep agents and skills under
`.beeuni/opencode/`. Beeuni reads both layouts.

## An agent is two files

Each agent has two parts:

- **Behavior** — a markdown file, `agents/<name>.md` by default. Its
  frontmatter sets the model, mode, and permission rules. Its body is the
  system prompt.
- **Governance** — an entry in `beeuni.yaml`'s `agents` map, keyed by the agent
  name. It sets what the agent may access: connectors, secrets, skills, Apps,
  Beeuni permissions, and [tools](/docs/project/tools#who-may-use-which-tool).
  Its `file` field names the behavior file.
  The map can live in a file the manifest lists under
  [`imports:`](/docs/project/manifest#imports); `default_agent` stays in `beeuni.yaml`.

The manifest never sets a prompt or mode. The `.md` file never sets
platform access. See [the manifest reference](/docs/project/manifest) for
every governance field.

### Where the agent file lives

```yaml
agents:
  support:
    file: agents/support.md
```

- `file` is a repo-relative path. It must end in `.md`.
- It must not start with `/`. It must not contain a `.` or `..` segment.
- Without `file`, Beeuni reads `agents/<name>.md`, then
  `.beeuni/opencode/agents/<name>.md`.
- When the dashboard saves an agent that has a `.md`, it writes `file` with that path.
- The API refuses to change `file`. To move an agent, move its `.md` and
  update `file` in `beeuni.yaml` in the same commit.

The full path rules are in
[the manifest reference](/docs/project/manifest#the-agent-file).

## Governance is deny-by-default

An agent with no `connectors`, `secrets`, `skills`, `apps`, or `beeuni_permissions` key gets
none of that access. `apps` lists the [Beeuni Apps](/docs/feature-flags/apps#agents-and-apps)
the agent may open when an App is restricted or private. This grant is the second of the two bindings: the agent
also holds a role as a `service_account` principal — its ceiling — and a
session can only do what both allow. See
[Agent permissions](/docs/project/permissions) and
[One vocabulary, two bindings](/docs/accounts#one-vocabulary-two-bindings). Set a field to `all` to grant full access, or list
specific names. `default_agent` in `beeuni.yaml` names the agent a session
starts when you request no agent.

Set each grant from the dashboard — Customize → Agents → the agent, one page
per grant set on the Access rail: Skills, Connectors, Secrets, Apps, Beeuni
permissions — or from the CLI with `beeuni agents scope <agent>`
(`--secrets`, `--connectors`, `--apps`). The Apps page appears only when the
project has the [Apps](/docs/feature-flags/apps) feature flag on. Every path
writes the same `agents.<name>` block in `beeuni.yaml`.

Legacy `beeuni.toml` (v1) projects list agents in an array, not a map, and
grant full access by default. Set specific grants to restrict access. See
[the manifest reference](/docs/project/manifest).

## Skills give an agent know-how

A skill is a markdown file at `skills/<name>/SKILL.md`.
The harness loads a skill on demand — Beeuni does not inject skill bodies
into every prompt. on the default runtime the agent calls the `skill` tool. on the experimental runtime the
system prompt lists each skill's name and description, and the agent reads
the file. An agent's `skills` grant in `beeuni.yaml`
controls which skills it may load.

## How a session picks its agent

Creating a session accepts an `agent_name`. Beeuni starts that agent for the
session. If you omit `agent_name`, Beeuni uses the project's `default_agent`.
Set the default agent from the dashboard, the API, or the SDK. Each writes
`default_agent` to `beeuni.yaml` and commits the change to the project's
default branch.

An agent acts as itself: its Beeuni permissions within its ceiling role,
whoever runs it. Starting a session does not lend the agent your own role.
See [Agent permissions](/docs/project/permissions).

New or changed agents and skills reach future sessions only after a
[change request](/docs/work/change-requests) merges them into the default
branch. Connect external tools before an agent can use them; see
[Connectors](/docs/connect/connectors).