Agent Development

Чеклист создания нового агента. Следуем Policy E: draft → review → approval → deploy.

Governance (Policy E)

Policy E — Draft Before Deploy: Новые агенты/процессы/workflows: draft → review → approval → deploy. No auto-deploy for critical things.

Draft

Черновик в миграции

Review

Код-ревью + тест

Approval

Подтверждение

Deploy

is_active=true

Чеклист создания агента

Определить цель и описание

□Сформулировать goal — что агент делает (добавляется в system prompt)
□Написать description — человеческое описание для документации
□Определить уникальный agent_code (snake_case)

-- Пример: agent для финансовой аналитики
agent_code: 'finance_analyst'
goal: 'Analyze financial data and produce investment insights'
description: 'Runs financial calculations, risk assessments, and portfolio analysis'

Определить инструменты

□allowed_tools — что агент МОЖЕТ использовать
□forbidden_tools — что агент НЕ МОЖЕТ использовать (safety)
□Проверить, что инструменты реализованы в internal_api или n8n

-- finance_analyst: может читать данные, но не может web_search
allowed_tools: ARRAY['db_query', 'rag_search']
forbidden_tools: ARRAY['web_search']  -- Safety: нет внешних запросов

Выбрать модели

□preferred_models — модели в порядке предпочтения
□Учитывать задачу: код → qwen2.5-coder, анализ → gemma3:4b
□Указать fallback модель (обычно phi4-mini)

-- Для финансового анализа нужна точность
preferred_models: ARRAY['gemma3:4b', 'phi4-mini']
default_temperature: 0.3  -- Низкая для точности

Определить response_contract

□format — markdown / json / code
□max_tokens — максимальная длина ответа
□language — auto / en / ru

response_contract: '{
  "format": "markdown",
  "max_tokens": 2048,
  "language": "auto"
}'::jsonb

Определить поведенческие параметры

□chat_mode — both / interactive / background
□max_delegation_depth — 0-3 (глубина делегирования)
□can_create_methods — true/false (может создавать методы)

-- Финансовый агент: интерактивный, не делегирует
chat_mode: 'interactive'
max_delegation_depth: 0
can_create_methods: false

Создать миграцию

□Файл: db/init/XXX_my_agent.sql (XXX — номер миграции)
□INSERT INTO agent_profile с is_active=false (draft)
□INSERT INTO agent_selection_policy для маппинга intent

-- db/init/400_finance_analyst.sql
INSERT INTO clowbot.agent_profile (
  agent_code, goal, description,
  allowed_tools, forbidden_tools, preferred_models,
  default_temperature, response_contract,
  chat_mode, max_delegation_depth, can_create_methods,
  is_active
) VALUES (
  'finance_analyst',
  'Analyze financial data and produce investment insights',
  'Runs financial calculations, risk assessments, and portfolio analysis',
  ARRAY['db_query', 'rag_search'],
  ARRAY['web_search'],
  ARRAY['gemma3:4b', 'phi4-mini'],
  0.3,
  '{"format": "markdown", "max_tokens": 2048}'::jsonb,
  'interactive',
  0,
  false,
  false  -- Draft mode
);

INSERT INTO clowbot.agent_selection_policy (
  agent_code, match_intent, match_process_code, match_scope, priority
) VALUES (
  'finance_analyst',
  ARRAY['finance', 'investment', 'portfolio'],
  ARRAY[],
  ARRAY['direct'],
  80
);

Добавить методы (опционально)

□Если нужны специфичные методы — INSERT INTO agent_methods
□Определить method_type: n8n_workflow / internal_api / process / llm_direct
□Указать input_contract и output_contract

INSERT INTO clowbot.agent_methods (
  agent_code, method_type, method_name, method_ref,
  description, priority, input_contract, output_contract
) VALUES (
  'finance_analyst', 'internal_api', 'portfolio_analysis',
  '/internal/finance/portfolio',
  'Portfolio risk analysis', 100,
  '{"portfolio_id": "uuid"}'::jsonb,
  '{"risk_score": "number", "recommendations": "array"}'::jsonb
);

Тестирование (smoke test)

□Вызвать POST /internal/agent/select с intent агента
□Проверить, что вернулся правильный agent_code
□Вызвать POST /internal/process/execute с тестовым запросом
□Проверить ответ в Telegram

# Smoke test
curl -X POST http://localhost:28000/internal/agent/select \
  -H "Authorization: Bearer $INTERNAL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"intent": "finance", "scope": "direct"}'

# Ожидаем: selected_agent_code = "finance_analyst"

Review и Approval

□Отправить на code review
□Получить approval от владельца
□Документировать в wiki

Deploy

□UPDATE agent_profile SET is_active = true WHERE agent_code = '...'
□Создать финальную миграцию с is_active=true
□Протестировать в production

-- Миграция для активации
UPDATE clowbot.agent_profile
SET is_active = true, updated_at = now()
WHERE agent_code = 'finance_analyst';

Полный пример: Создание telegram_notifier

-- db/init/401_telegram_notifier.sql
-- Agent for scheduled Telegram notifications

INSERT INTO clowbot.agent_profile (
  agent_code, goal, description,
  allowed_tools, forbidden_tools, preferred_models,
  default_temperature, response_contract,
  chat_mode, max_delegation_depth, can_create_methods,
  is_active
) VALUES (
  'telegram_notifier',
  'Send scheduled notifications and reminders to users via Telegram',
  'Handles recurring reminders, daily digests, and scheduled messages',
  ARRAY['db_query'],                    -- Can read DB for schedules
  ARRAY['web_search'],                  -- No web access needed
  ARRAY['phi4-mini'],
  0.5,
  '{"format": "markdown", "max_tokens": 1024, "language": "auto"}'::jsonb,
  'background',                         -- Only triggered by scheduler
  0,                                    -- No delegation
  false,
  true                                  -- Active immediately (non-critical)
);

-- Selection policy
INSERT INTO clowbot.agent_selection_policy (
  agent_code, match_intent, match_process_code, match_scope, priority
) VALUES (
  'telegram_notifier',
  ARRAY['notify', 'reminder', 'schedule'],
  ARRAY['daily_digest', 'content_factory_digest'],
  ARRAY['direct', 'group'],
  60
);

-- Methods
INSERT INTO clowbot.agent_methods (
  agent_code, method_type, method_name, method_ref, description, priority
) VALUES
  ('telegram_notifier', 'process', 'daily_digest', 'daily_digest', 'Daily digest process', 100),
  ('telegram_notifier', 'internal_api', 'send_reminder', '/internal/reminder/send', 'Send reminder', 90);

Quick Reference

Поле	Обязательное	Пример
agent_code	✅	'my_agent'
goal	✅	'Do X and produce Y'
description	✅	'Human readable description'
allowed_tools	✅	ARRAY['db_query']
forbidden_tools	✅	ARRAY['web_search']
preferred_models	✅	ARRAY['phi4-mini']
default_temperature	✅	0.7
response_contract	✅	{format: markdown}
chat_mode	❌ default: both	'background'
max_delegation_depth	❌ default: 0	2
is_active	❌ default: true	false (draft)

Связи

→ Agent Profiles

Структура agent_profile

→ Agent Methods

Добавление методов

→ Database Migrations

Работа с миграциями

→ Platform Constitution

Policy E: Draft Before Deploy