# Agents

An agent is a markdown file that OpenCode runs; the manifest only governs its access.

Canonical page: https://themachine.myapps.ai/docs/project/agents

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

## OpenCode runs every session

OpenCode, the open-source coding-agent runtime, runs every session. The
`kortix-agent` daemon starts it as `opencode serve`, with its config
directory pointed at the project's `.kortix/opencode/` folder.

## An agent is two files

Each agent has two parts:

- **Behavior** — a markdown file at `.kortix/opencode/agents/<name>.md`. Its
  frontmatter sets the model, mode, and tools. Its body is the system prompt.
- **Governance** — an entry in `kortix.yaml`'s `agents` map, keyed by the same
  name. It sets what the agent may access on Machine: secrets, skills, and
  CLI actions.

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

## Governance is mostly deny-by-default

An agent with no `secrets`, `skills`, or `kortix_cli` key gets none of that
access. Set a field to `all` to grant full access, or list specific names.
`default_agent` in `kortix.yaml` names the agent a session starts when you
request no agent.

Two kinds of access are project-wide and ignore the agent's lists:

- **Connectors.** Every agent can call every connector connected on the
  project. An agent's `connectors` list no longer narrows this. Each
  connector's approval policies still apply, and a session for an agent with
  `connectors_required` still fails to start until the connectors it names
  are connected.
- **Sandbox secrets.** Every agent receives every secret whose delivery is
  Sandbox. The `secrets` list gates only Network boundary and Machine service
  delivery. See [Secrets](/docs/project/secrets).

Legacy `kortix.toml` (v1) projects list agents in an array, not a map. In v1
an omitted `env` (the v1 name for `secrets`) means `all`, but `all` never
delivers a Network boundary or Machine service secret: those always need the
identifier listed by name. An omitted `kortix_cli` means none, as in v2. See
[Legacy TOML](/docs/project/legacy-toml) and [the manifest
reference](/docs/project/manifest).

## Skills give an agent know-how

A skill is a markdown file at `.kortix/opencode/skills/<name>/SKILL.md`.
OpenCode loads a skill on demand when the agent calls it — Machine does not
inject skills into every prompt. An agent's `skills` grant in `kortix.yaml`
controls which skills it may load.

## How a session picks its agent

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

An agent never exceeds the access of the person or token that started the
session.

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