Структура Agent Template

agent_template/
  app/
    main.py          — FastAPI приложение, эндпоинты /health и /run
    runner.py        — Agentic loop (Claude API + tool use)
    models.py        — Pydantic модели (TaskRequest, TaskResponse)
    metrics.py       — Отправка метрик в оркестратор
    config.py        — Настройки через .env (pydantic-settings)
    logger.py        — Структурированный логгер (JSON)
  tools/
    __init__.py      — TOOL_REGISTRY (регистрация инструментов)
    example_tools.py — Примеры: time, calculator, web_search stub
  tests/
    test_agent.py    — Базовые тесты /run и /health
  Dockerfile
  docker-compose.yml
  requirements.txt
  .env.example
  README.md

app/main.py

Точка входа FastAPI. Регистрирует два обязательных эндпоинта:

• POST /run — запуск задачи, делегирует в runner.py
• GET /health — проверка работоспособности, возвращает {"status": "ok"}

Не изменяйте сигнатуры эндпоинтов — оркестратор работает с ними напрямую.

app/runner.py

Основная логика агента: agentic loop с Claude API и tool use. Здесь вы:

• Формируете системный промпт
• Передаёте задачу в Claude
• Обрабатываете вызовы инструментов (tool_use блоки)
• Возвращаете финальный результат

app/models.py

Pydantic-модели для входных и выходных данных:

class TaskRequest(BaseModel):
    task_id: str
    input: str
    config: dict = {}

class TaskResponse(BaseModel):
    task_id: str
    status: str  # "success" | "error"
    output: str
    metrics: dict
    error: str | None = None

app/metrics.py

Отправка метрик по завершении задачи. Заполняйте metrics в ответе:

metrics = {
    "duration_sec": 1.24,
    "input_tokens": 312,
    "output_tokens": 48,
    "steps": 2
}

app/logger.py

Структурированный логгер на базе structlog. Используйте его вместо print:

from app.logger import get_logger
logger = get_logger(__name__)
logger.info("task_started", task_id=task_id, input_length=len(input))

tools/

Инструменты (функции) для агента. Каждый файл — один инструмент или группа инструментов. Все инструменты регистрируются в tools/__init__.py в словаре TOOL_REGISTRY.