Skip to content
BeeuniBeeuni
English
EnglishDeutschItaliano中文日本語PortuguêsFrançaisEspañolСрпски
Esc
↑↓navigate↵open⌘Jpreview
On this page

Agents

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. 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 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. Its file field names the behavior file. The map can live in a file the manifest lists under 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 for every governance field.

Where the agent file lives

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.

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 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 and 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 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.

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.

New or changed agents and skills reach future sessions only after a change request merges them into the default branch. Connect external tools before an agent can use them; see Connectors.

Was this page helpful?