---
name: agent-os-build-agent
description: Создать или изменить агента Agent OS только на YAML и опциональных скриптах (JavaScript или Rhai) — agent.yaml, инструменты, хуки, тесты, бенчмарк-сценарии. Используй, когда просят создать агента, добавить возможность или изменить поведение/инструкции.
---

# Agent OS — создание агента

Агент — это подкаталог `config/agents/<name>/`. Всё на YAML; без Rust, без
пересборки. Полный справочник: `docs/04-building-an-agent.md`.

## Структура каталога

```
config/agents/<name>/
├── agent.yaml              # ОБЯЗАТЕЛЕН: name, welcome, instructions, tool/hook-ссылки
├── tools/                  # YAML-конфиги инструментов (через tool_files)
│   └── *.yaml
├── hooks/                  # YAML-конфиги хуков (через hook_files)
│   └── *.yaml
├── bench/
│   └── scenarios.yaml      # E2E-сценарии бенчмарка
└── tests/                  # fixture/live-тесты инструментов
    └── *.yaml
```

## Минимальный `agent.yaml`

```yaml
name: my-agent
welcome: |
  👋 Привет! Чем помочь?
instructions: |
  You are a helpful assistant.
  Answer in Russian. Be concise.
tools:                 # встроенные инструменты по имени
  - http_fetch
tool_files:            # YAML-инструменты, пути отн. ЭТОЙ папки агента
  - tools/my_tool.yaml
hook_files:            # хуки
  - hooks/faq_cache.yaml
```

## Полный справочник полей `agent.yaml`

| Поле | Обязат. | Описание |
|---|---|---|
| `name` | да | имя шаблона (уникальное) |
| `instructions` | да | системный промпт |
| `welcome` | нет | сообщение при открытии виджета |
| `tools` | нет | встроенные: `http_fetch`, `fs_read`, `job_done` |
| `tool_files` | нет | пути к YAML-инструментам (отн. папки агента) |
| `hooks` | нет | имена хуков (зарегистрированы при старте) |
| `hook_files` | нет | пути к YAML-хукам (отн. папки агента) |
| `max_context_tokens` | нет | лимит контекста (по умолчанию 32000) |
| `model` | нет | именованная модель из `server.yaml → models:` |
| `output_schema` | нет | JSON Schema → агент завершается `job_done` с валидированным payload |
| `budget` | нет | перекрытие бюджета `{refill_per_sec, max_bucket, max_total}` |
| `budget_group` | нет | имя общей бюджетной группы |
| `budget_messages` | нет | сообщения исчерпания: `session_exhausted`, `user_exhausted`, `group_exhausted`, `rate_limited` |
| `inherit_budget` | нет | дочерние процессы наследуют группу |
| `parent` | нет | имя родителя (дерево процессов) |
| `telegram` | нет | `{token_env, allowed_user_ids, show_typing, show_tool_calls}` |
| `email` | нет | `{imap_host, imap_port, imap_username, imap_password_env, allowed_senders, smtp, notify, poll_secs}` |
| `cron` | нет | задания по расписанию этого агента |

Секция `agents:` в `budgets.yaml` перекрывает `budget_group`/`budget`.

## Практики инструкций

- Пиши **какой инструмент когда вызывать**, включая многошаговые цепочки.
- Требуй копировать `links[]` из вывода инструмента в ответ — ссылки обязательны.
- Фиксируй формат и язык ответа.
- Используй `__GEOIP__` для подстановки города пользователя.
- Держи агента «приземлённым»: не угадывать, а проверять вызовом.

## Чек-лист

1. `config/agents/<name>/agent.yaml` с `name`, `welcome`, `instructions`, `tool_files`.
2. Один или несколько инструментов в `tools/` (см. скилл `agent-os-tools`).
3. Опционально хуки в `hooks/` (см. скилл `agent-os-hooks`).
4. Опционально `bench/scenarios.yaml` (см. `docs/16-benchmarking.md`).
5. Проверь инструмент через `site_tool` (см. `docs/09-operations.md`).
6. Проверь поведение через `agent_bench`.

Рестарт не нужен при `live_reload: true` (по умолчанию) — новые сессии подхватывают
правки.
