# `Sagents.SubAgent.Task`

Behaviour for task modules that describe a named sub-agent "skill".

Each task module describes a sub-agent that is registered on the parent
agent's `Sagents.Middleware.SubAgent` and invoked via the built-in
`task` tool. The sub-agent runs in an isolated context with its own
middleware/tool stack, performs task-specific work, and reports back
to the parent.

Task modules are typically compiled into `Sagents.SubAgent.Compiled`
entries by host applications, which combine the task's `instructions/0`
with `Sagents.SubAgent.task_subagent_boilerplate/0` to form the child
agent's system prompt.

## Callbacks

- `task_name/0` — short, kebab-case identifier exposed to the parent LLM
  as the `subagent_type` enum value (e.g. `"search-web"`).
- `description/0` — one-line blurb surfaced in the `task` tool's auto-
  generated menu. Always in the parent's context.
- `use_instructions/0` — *optional.* Detailed "how to invoke this" guide
  for the parent LLM. Lazy-loaded via `get_task_instructions` only
  when the parent decides it wants to use this task. Describes
  prerequisites (what inputs/source data must exist), what to pass
  in the `instructions` arg, and what outputs the task produces. If
  not implemented, the host should treat this as "no lazy-loaded
  docs" — the task is invoked using only `description/0` as parent-
  visible guidance.
- `instructions/0` — the task's internal working prompt. Baked into the
  child sub-agent's system prompt at invocation. Never shown to the
  parent. Should focus on the substantive procedure — the universal
  boilerplate (no user questions, complete-or-fail, etc.) is supplied
  by `Sagents.SubAgent.task_subagent_boilerplate/0`.
- `display_text/0` — *optional.* Human-facing status string shown in
  the host UI while this task is running. If not implemented, the
  middleware falls back to a generic `"Running task"` label (see
  `Sagents.Middleware.SubAgent`); host compilers may instead derive
  a humanized form of `task_name/0`.
- `model_override/0` — *optional.* If defined and returns a non-nil
  value, the host should use the returned model (e.g. a configured
  chat-model struct) for this task's sub-agent instead of the default
  model supplied at compile time. Useful for narrow, bounded tasks
  where a cheaper/faster model is sufficient (e.g. summarization,
  classification). Returning `nil` — or not implementing this
  callback at all — means "use the host's default."

Host compilers should guard optional callbacks with
`function_exported?/3` before calling them, and supply the documented
fallback when absent.

# `description`

```elixir
@callback description() :: String.t()
```

# `display_text`

*optional* 

```elixir
@callback display_text() :: String.t()
```

# `instructions`

```elixir
@callback instructions() :: String.t()
```

# `model_override`

*optional* 

```elixir
@callback model_override() :: term() | nil
```

# `task_name`

```elixir
@callback task_name() :: String.t()
```

# `use_instructions`

*optional* 

```elixir
@callback use_instructions() :: String.t()
```

---

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