# `ExAthena.Agents`
[🔗](https://github.com/udin-io/ex_athena/blob/v0.7.1/lib/ex_athena/agents.ex#L1)

Custom agent definitions loaded from YAML/markdown files.

An *agent* is a named bundle of run options — model, provider,
tools, permissions, mode, isolation strategy, and a system-prompt
addendum — that callers can spawn by name via
`ExAthena.Tools.SpawnAgent.execute/2` with `agent: "<name>"`.

This is opencode's `.opencode/agents/<name>.md` pattern adapted to
ex_athena. The Claude Code paper documents the same idea
(`.claude/agents/*.md`) for delegating bounded tasks.

## Layout

    ~/.config/ex_athena/agents/<name>.md   # user-level
    <cwd>/.exathena/agents/<name>.md       # project-level
    priv/agents/<name>.md                  # builtin fallbacks (ship with the package)

Project agents override user-level agents with the same name; the
built-in fallbacks (`general`, `explore`, `plan`) are used only
when the host hasn't defined one with the same name.

## Frontmatter schema

    ---
    name: explore
    description: Read-only fast investigation
    model: claude-haiku-4-5
    provider: anthropic
    tools: [read, glob, grep, web_fetch]
    permissions: plan
    mode: react
    isolation: in_process
    ---

    You are a read-only research assistant. Walk the codebase and
    report findings concisely. Do not modify any files.

Only `name` is required. Anything else inherits from the spawning
parent (provider, model, tools, etc.) or hard-coded defaults
(`mode: :react`, `isolation: :in_process`, `permissions: :default`).

# `apply_to_opts`

```elixir
@spec apply_to_opts(
  ExAthena.Agents.Definition.t(),
  keyword()
) :: keyword()
```

Apply a definition's frontmatter to a base keyword list of run
options. Definition fields override the parent's values when set;
unset fields pass through.

# `discover`

```elixir
@spec discover(
  String.t(),
  keyword()
) :: %{required(String.t()) =&gt; ExAthena.Agents.Definition.t()}
```

Discover all agent definitions for `cwd`.

Returns a map keyed by name. Resolution: builtin → user → project,
later sources overriding earlier ones.

## Options

  * `:user_dir` — override the user-level agents directory.
  * `:project_dir` — override the project-level directory.
  * `:builtin_dir` — override the builtin fallbacks (mainly for
    tests).

# `fetch`

```elixir
@spec fetch(map(), String.t()) ::
  {:ok, ExAthena.Agents.Definition.t()} | {:error, :not_found}
```

Look up an agent by name. Returns `{:ok, def}` or `{:error, :not_found}`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*