agentyoke 0.1.0

Тонкий harness-фреймворк для AI-агентов: сменный провайдер рантайма (API/Claude Code/Codex), middleware-pipeline и слой skills/MCP.

agentyoke

Тонкий harness-фреймворк для AI-агентов: сменный провайдер рантайма (API / Claude Code / Codex), middleware-pipeline и слой skills/MCP.

Один интерфейс — любой агентный рантайм. Yoke (ярмо/упряжь) — это та самая упряжь, что заставляет несколько волов тянуть в одну сторону. agentyoke делает то же с разными агентными рантаймами и моделями: прикладной код агента не знает, кто внутри — собственный цикл над LiteLLM, Claude Code или Codex.

✅ Статус: 0.1.0 — рабочая реализация. Конфиг, middleware-pipeline (logging / cost / rate-limit / guardrails / cache / retry), observability, загрузчик skills, ApiProvider (agentic-loop) и CLI-провайдеры реализованы и покрыты тестами (ruff + mypy --strict + pytest).

---

Ключевая идея

1. Гибрид: тонкое собственное ядро — не монолитный фреймворк. Ядро владеет контрактами (AgentProvider, AgentEvent); Pydantic отвечает за конфиг и валидацию, а собственный agentic-loop ходит в модель через LiteLLM.
2. Provider как сменный модуль на двух уровнях:
   • модель — через LiteLLM (любой LLM за единым API);
   • агентный рантайм — через AgentProvider (свой цикл / Claude Code / Codex).
3. CLI как провайдер — Claude Code и Codex CLI за тем же интерфейсом, что и API.
4. Middleware-pipeline — логи, стоимость, лимиты, кеш, guardrails как композируемые кросс-срезы, а не код внутри ядра.
5. Skills/SKILL.md + AGENTS.md + MCP — три слоя инструкций и доступа.
6. OpenTelemetry GenAI conventions — наблюдаемость из коробки.

flowchart LR
    App["Агент-приложение<br/>(agents/&lt;name&gt;)"] --> MW["Middleware<br/>pipeline"]
    MW --> P{"AgentProvider"}
    P -->|api| API["ApiProvider<br/>(собственный цикл + LiteLLM)"]
    P -->|claude_code| CC["ClaudeCodeProvider<br/>(Claude Agent SDK / CLI)"]
    P -->|codex| CX["CodexProvider<br/>(Codex CLI / SDK)"]
    API --> M[("LLM через LiteLLM")]
    MW -.->|спаны/метрики| OTel["OpenTelemetry"]

Установка

# из PyPI (после первого релиза: тег v0.1.0 публикует пакет через CI)
pip install agentyoke
# опциональные CLI-рантаймы:
pip install "agentyoke[claude-code]"

Quick start

# для разработки — из исходников
uv venv --python 3.12
uv pip install -e ".[dev]"

# запуск примера агента (нужен ключ модели, напр. ANTHROPIC_API_KEY)
python -m agents.example.run

Высокоуровневый API — класс Agent: загружает конфиг, собирает провайдер и middleware-цепочку, и отдаёт либо поток событий, либо агрегированный результат.

from agentyoke import Agent, Message, ToolRegistry

tools = ToolRegistry()


@tools.register
def current_time() -> str:
    """Текущее время."""
    from datetime import UTC, datetime
    return datetime.now(UTC).isoformat()


agent = Agent.from_config("agents/example/config.yaml", tools=tools)

# Поток событий (TextDelta / ToolCallEvent / UsageEvent / ...):
async for event in agent.run_stream([Message(role="user", content="Который час?")]):
    print(event)

# Или агрегированный результат целиком:
result = await agent.run([Message(role="user", content="Который час?")])
print(result.text, result.usage)

Сменить рантайм — это поменять одну строку provider: в config.yaml (api → claude_code → codex). Прикладной код не меняется.

Если выбран provider: api, но ANTHROPIC_API_KEY не задан, агент прозрачно использует локальную сессию Claude Code (провайдер claude_code) — удобно для подписочного доступа без API-ключа. Отключается флагом Agent(..., local_session_fallback=False).

Документация

Документ	О чём
docs/ARCHITECTURE.md	Архитектурный обзор: два уровня провайдеров, ядро, потоки
docs/PROVIDERS.md	Спека AgentProvider, AgentEvent, контракт каждого провайдера
docs/MIDDLEWARE.md	Middleware-pipeline, встроенные middleware, 3 уровня политик
docs/SKILLS.md	Три слоя: skills (SKILL.md) / AGENTS.md / MCP
docs/OBSERVABILITY.md	OpenTelemetry, GenAI semantic conventions
docs/ROADMAP.md	Этапы 0–4 с оценками сроков
docs/REFERENCES.md	Источники: Omnigent, Pydantic AI, LiteLLM и др.

Структура репозитория

agentyoke/
├── src/agentyoke/        # ядро (тонкое): провайдеры, middleware, skills, observability
├── agents/               # агенты-приложения (каждый — свой config.yaml)
├── docs/                 # спецификации (источник истины)
├── CLAUDE.md / AGENTS.md # инструкции для агентных инструментов
└── pyproject.toml

---

English summary

agentyoke is a thin harness framework for AI agents. The core idea is a slim own core rather than a monolithic framework: the core owns the contracts, while its own agentic loop talks to models through LiteLLM. Providers are swappable on two levels: the model (via LiteLLM) and the agent runtime (AgentProvider: own loop, Claude Code, or Codex — "CLI as a provider"). Cross-cutting concerns (logging, cost tracking, rate limits, caching, guardrails) live in a composable middleware pipeline. Instructions and access come in three layers — Skills (SKILL.md) + AGENTS.md + MCP — and observability follows OpenTelemetry GenAI semantic conventions.

Switching the runtime is a one-line provider: change in config.yaml; the application agent code stays the same. See docs/ for full specifications.

Status: 0.1.0 — the core is implemented and tested: config loading, the middleware pipeline, observability, the skills loader, the ApiProvider agentic loop, and the CLI providers.

License

MIT.