Agent Card: спецификация агента — skills, capabilities, ограничения

{
  "name": "Data Analysis Agent",
  "description": "Анализирует структурированные данные, строит графики и пишет отчёты. Работает с CSV, JSON и SQL-источниками.",
  "url": "https://agents.example.com/data-analyst",
  "version": "1.2.0",
  "provider": {
    "organization": "Example Corp",
    "url": "https://example.com"
  },
  "defaultInputModes": ["text", "data", "file"],
  "defaultOutputModes": ["text", "data", "file"],
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "stateTransitionHistory": true
  },
  "authentication": {
    "schemes": ["Bearer"],
    "credentials": null
  },
  "skills": [
    {
      "id": "data-analysis",
      "name": "Анализ данных",
      "description": "Статистический анализ датасетов: дескриптивная статистика, выбросы, корреляции, тренды. Принимает CSV/JSON, возвращает структурированный отчёт.",
      "tags": ["analytics", "statistics", "csv", "json"],
      "examples": [
        "Проанализируй продажи за Q3 и найди аномалии",
        "Посчитай корреляцию между метриками retention и revenue"
      ],
      "inputModes": ["text", "file", "data"],
      "outputModes": ["text", "data"]
    },
    {
      "id": "charting",
      "name": "Построение графиков",
      "description": "Строит визуализации: линейные, столбчатые, тепловые карты, scatter plots. Возвращает PNG или интерактивный HTML.",
      "tags": ["visualization", "charts", "matplotlib", "plotly"],
      "examples": [
        "Построй график продаж по месяцам с трендовой линией",
        "Сделай heatmap корреляций для таблицы metrics"
      ],
      "inputModes": ["text", "data"],
      "outputModes": ["file", "text"]
    },
    {
      "id": "sql-query",
      "name": "SQL-запросы",
      "description": "Пишет и выполняет SELECT-запросы к подключённым базам данных. Только чтение, DDL запрещён.",
      "tags": ["sql", "database", "postgresql", "sqlite"],
      "examples": [
        "Найди топ-10 пользователей по выручке за последний месяц",
        "Сколько заказов в статусе pending больше 3 дней"
      ],
      "inputModes": ["text"],
      "outputModes": ["text", "data"]
    }
  ]
}

{
  "name": "Code Review Agent",
  "description": "Проверяет Python-код на качество, безопасность и стиль. НЕ пишет новый код — только ревьюирует существующий. НЕ работает с TypeScript, Java, Go. Максимальный размер файла: 500 КБ. Не имеет доступа к интернету.",
  "skills": [
    {
      "id": "security-audit",
      "name": "Аудит безопасности",
      "description": "Ищет уязвимости в Python-коде: инъекции, небезопасные десериализации, hardcoded secrets, небезопасные HTTP-запросы. Анализирует только статически — не запускает код. Возвращает список найденных проблем с severity и рекомендациями по исправлению.",
      "tags": ["security", "python", "static-analysis", "owasp"],
      "examples": [
        "Проверь этот файл на SQL-инъекции",
        "Есть ли в коде hardcoded API keys?"
      ]
    }
  ]
}

"""
Структуры данных для Agent Card.
Совместимы со спецификацией A2A (Google, 2025).
"""
from __future__ import annotations
import json
from dataclasses import dataclass, field, asdict
from typing import Literal

InputMode  = Literal["text", "data", "file", "audio", "image"]
OutputMode = Literal["text", "data", "file", "audio", "image"]
AuthScheme = Literal["Bearer", "ApiKey", "OAuth2", "none"]


@dataclass
class AgentSkill:
    """Одна именованная возможность агента."""
    id: str                               # kebab-case, стабильный идентификатор
    name: str                             # Человекочитаемое название
    description: str                      # Описание для LLM-роутера
    tags: list[str] = field(default_factory=list)
    examples: list[str] = field(default_factory=list)
    input_modes: list[InputMode] = field(default_factory=list)
    output_modes: list[OutputMode] = field(default_factory=list)

    def __post_init__(self):
        if not self.id or not self.id.replace("-", "").isalnum():
            raise ValueError(f"Skill id должен быть kebab-case: '{self.id}'")
        if not self.description:
            raise ValueError(f"Skill '{self.id}' должен иметь description")


@dataclass
class AgentCapabilities:
    """Технические возможности агента."""
    streaming: bool = False
    push_notifications: bool = False
    state_transition_history: bool = False


@dataclass
class AgentAuthentication:
    schemes: list[AuthScheme] = field(default_factory=lambda: ["none"])
    credentials: str | None = None


@dataclass
class AgentProvider:
    organization: str
    url: str = ""


@dataclass
class AgentCard:
    """
    Полная спецификация агента.
    Публикуется по /.well-known/agent.json
    """
    name: str
    description: str
    url: str
    skills: list[AgentSkill]
    version: str = "1.0.0"
    provider: AgentProvider | None = None
    default_input_modes: list[InputMode] = field(
        default_factory=lambda: ["text"]
    )
    default_output_modes: list[OutputMode] = field(
        default_factory=lambda: ["text"]
    )
    capabilities: AgentCapabilities = field(
        default_factory=AgentCapabilities
    )
    authentication: AgentAuthentication = field(
        default_factory=AgentAuthentication
    )

    def __post_init__(self):
        if not self.skills:
            raise ValueError("Agent Card должна содержать хотя бы один skill")
        ids = [s.id for s in self.skills]
        if len(ids) != len(set(ids)):
            raise ValueError("Skill ids должны быть уникальными")

    def to_json(self, indent: int = 2) -> str:
        """Сериализует в JSON по спецификации A2A (camelCase)."""
        d = asdict(self)
        return json.dumps(_to_camel(d), ensure_ascii=False, indent=indent)

    @classmethod
    def from_json(cls, text: str) -> "AgentCard":
        """Десериализует из JSON."""
        d = _from_camel(json.loads(text))
        skills = [AgentSkill(**s) for s in d.pop("skills")]
        caps   = AgentCapabilities(**d.pop("capabilities", {}))
        auth   = AgentAuthentication(**d.pop("authentication", {}))
        prov   = AgentProvider(**d.pop("provider")) if d.get("provider") else None
        return cls(skills=skills, capabilities=caps, authentication=auth,
                   provider=prov, **d)

    def matches_task(self, task: str) -> list[AgentSkill]:
        """
        Простой поиск подходящих skills по ключевым словам задачи.
        В реальных системах используется embedding-similarity.
        """
        task_lower = task.lower()
        matched = []
        for skill in self.skills:
            score = 0
            if any(tag in task_lower for tag in skill.tags):
                score += 2
            if any(word in task_lower
                   for word in skill.description.lower().split()
                   if len(word) > 4):
                score += 1
            if any(ex_word in task_lower
                   for ex in skill.examples
                   for ex_word in ex.lower().split()
                   if len(ex_word) > 4):
                score += 1
            if score > 0:
                matched.append((score, skill))
        return [s for _, s in sorted(matched, reverse=True)]


# ── Утилиты конвертации snake_case ↔ camelCase ───────────────────────

def _to_camel(d):
    if isinstance(d, dict):
        return {_snake_to_camel(k): _to_camel(v) for k, v in d.items() if v is not None}
    if isinstance(d, list):
        return [_to_camel(i) for i in d]
    return d

def _from_camel(d):
    if isinstance(d, dict):
        return {_camel_to_snake(k): _from_camel(v) for k, v in d.items()}
    if isinstance(d, list):
        return [_from_camel(i) for i in d]
    return d

def _snake_to_camel(s: str) -> str:
    parts = s.split("_")
    return parts[0] + "".join(p.capitalize() for p in parts[1:])

def _camel_to_snake(s: str) -> str:
    import re
    return re.sub(r"(?