Budujemy open-source'ową alternatywę Claude Code w Pythonie

Claude Code zmienił sposób, w jaki deweloperzy myślą o asystentach kodowania AI. Agent, który żyje w terminalu, czyta Twój codebase, edytuje pliki, uruchamia komendy — bez kart przeglądarki, bez kopiuj-wklej, bez żonglowania oknem kontekstu.

Ale jest pewien haczyk: to zamknięty monolityczny produkt. Nie możesz podmienić modelu. Nie możesz rozszerzyć zestawu narzędzi. Nie możesz wdrożyć go na własnej infrastrukturze. A jeśli budujesz agenty dla klientów — nie możesz wysłać Claude Code jako swojego produktu.

Chcieliśmy tej samej architektury — planowanie, checkpointy, edycja plików, human-in-the-loop — ale modularnej, open-source i zbudowanej na Pydantic AI. Więc to zbudowaliśmy.

Czym tak naprawdę jest pydantic-deepagents

pydantic-deepagents (pydantic-deep) to framework w Pythonie do budowania deep agentów w stylu Claude Code — takich, które planują, delegują, zapamiętują i samodzielnie się korygują. Dostępny jest w dwóch formach:

1. Framework — create_deep_agent() z 30+ opcjonalnymi funkcjami, które włączasz/wyłączasz
2. CLI — pydantic-deep chat — w pełni interaktywny asystent terminalowy

Oba są zbudowane na Pydantic AI i stosują ten sam wzorzec deep agent, który wykorzystują Claude Code, Devin i Manus AI.

Kluczowa różnica: wszystko jest modularne. Framework jest podzielony na 5 niezależnych pakietów open-source:

pydantic-deep              — rdzeń agenta + CLI
├── pydantic-ai-backend    — przechowywanie plików (lokalne, state, Docker, Daytona)
├── pydantic-ai-todo       — planowanie zadań z zależnościami
├── subagents-pydantic-ai  — synchroniczna/asynchroniczna delegacja agentów
├── summarization-pydantic-ai — zarządzanie kontekstem + sliding window
└── pydantic-ai-middleware — hooki cyklu życia, uprawnienia, śledzenie kosztów

Każdy pakiet działa samodzielnie. Możesz używać pydantic-ai-todo bez reszty. Możesz podmienić pydantic-ai-backend na własną warstwę przechowywania. Framework je komponuje — Ty wybierasz, czego potrzebujesz.

API jednej funkcji

Stworzenie agenta ze wszystkimi funkcjami wymaga jednego wywołania funkcji:

from pydantic_deep import create_deep_agent, DeepAgentDeps, StateBackend

agent = create_deep_agent(
    model="openai:gpt-4.1",
    instructions="You are a helpful coding assistant",
    include_plan=True,           # Planning subagent
    include_checkpoints=True,    # Save/rewind state
    include_memory=True,         # Persistent MEMORY.md
    include_skills=True,         # Slash commands
    cost_tracking=True,          # Budget enforcement
    cost_budget_usd=5.0,
)

deps = DeepAgentDeps(backend=StateBackend())
result = await agent.run("Refactor the auth module", deps=deps)

Każda funkcja to flaga boolean. Potrzebujesz zespołów? Dodaj include_teams=True. Chcesz hooki? Przekaż listę hooks. Framework automatycznie składa odpowiednie zestawy narzędzi, middleware i sekcje system promptu.

Checkpointy i cofanie stanu

To jest funkcja, która zmienia sposób pracy z agentami. Każde wywołanie narzędzia tworzy checkpoint — migawkę stanu konwersacji. Gdy agent pójdzie złą ścieżką (a pójdzie), cofasz stan:

from pydantic_deep import InMemoryCheckpointStore, RewindRequested

store = InMemoryCheckpointStore()
agent = create_deep_agent(
    include_checkpoints=True,
    checkpoint_store=store,
    checkpoint_frequency="every_tool",
)

while True:
    try:
        result = await agent.run(user_input, deps=deps, message_history=history)
        history = result.all_messages()
    except RewindRequested as e:
        print(f"Rewinding to '{e.label}'...")
        history = e.messages

Agent mówi “save_checkpoint(‘before refactor’)” przed ryzykownymi operacjami. Ty mówisz “rewind to ‘before refactor’”, gdy coś zepsuje. Stan konwersacji wraca do poprzedniego punktu — bez utraconego kontekstu, bez ponownego tłumaczenia zadania.

W CLI checkpointy wyświetlają się jako oznaczone migawki, między którymi możesz przeskakiwać. Jak commity git dla konwersacji z agentem.

Zespoły agentów

Pojedyncze agenty mają swoje limity przy złożonych zadaniach. Nasze rozwiązanie: płaskie zespoły ze współdzielonym stanem.

from pydantic_deep.toolsets.teams import AgentTeam, TeamMember

team = AgentTeam(
    name="backend-team",
    members=[
        TeamMember(name="alice", role="api-designer",
                   instructions="Focus on clean REST API design"),
        TeamMember(name="bob", role="db-architect",
                   instructions="Design efficient database schema"),
    ],
)

# Assign tasks with dependencies
task_a = await team.todos.add("Design the API schema", created_by="lead")
task_b = await team.todos.add("Implement endpoints",
                               blocked_by=[task_a], created_by="lead")

Każdy członek zespołu współdzieli SharedTodoList (bezpieczne dla asyncio pobieranie zadań z zależnościami) i TeamMessageBus do komunikacji peer-to-peer. Żadnych hierarchicznych łańcuchów subagentów — agenty koordynują się jako partnerzy, pobierają zadania i wysyłają sobie wiadomości, gdy potrzebują informacji.

Hooki — zdarzenia cyklu życia w stylu Claude Code

Każde wywołanie narzędzia w pydantic-deep wyzwala zdarzenia cyklu życia. Przechwytujesz je za pomocą hooków:

from pydantic_deep import Hook, HookEvent, HookInput, HookResult

async def safety_gate(hook_input: HookInput) -> HookResult:
    if "rm -rf" in str(hook_input.tool_input):
        return HookResult(allow=False, reason="Dangerous command blocked")
    return HookResult(allow=True)

agent = create_deep_agent(
    hooks=[
        Hook(
            event=HookEvent.PRE_TOOL_USE,
            handler=safety_gate,
            matcher="execute",
        ),
        Hook(
            event=HookEvent.POST_TOOL_USE,
            command="echo '$TOOL_NAME' >> /tmp/audit.log",
        ),
    ],
)

Trzy typy zdarzeń: PRE_TOOL_USE, POST_TOOL_USE, POST_TOOL_USE_FAILURE. Hooki mogą być handlerami Python lub komendami shell. Kod wyjścia 0 = zezwól, kod wyjścia 2 = odmów.

Niestandardowe komendy slash

Wrzuć plik Markdown do .pydantic-deep/commands/, a staje się komendą slash:

# /commit

Create a conventional git commit for the current changes.

## Instructions
1. Run `git diff --staged` to see what's staged
2. If nothing is staged, run `git add -A`
3. Generate a commit message following Conventional Commits
4. Run `git commit -m "..."` with the generated message

CLI dostarcza wbudowane komendy: /commit, /pr, /review, /test, /fix, /explain. Trzy zakresy odkrywania: wbudowane, na poziomie użytkownika (~/.pydantic-deep/commands/) i na poziomie projektu (.pydantic-deep/commands/).

Terminalowy UX w CLI

CLI (pydantic-deep chat) to miejsce, gdzie wszystko się łączy:

Podgląd diff do zatwierdzania zmian w plikach. Gdy agent chce edytować plik, widzisz kolorowy unified diff z paskami guttera przed zatwierdzeniem.

Pasek postępu kontekstu. Pasek statusu pokazuje nazwę modelu, skumulowany koszt i wizualny wskaźnik wykorzystania kontekstu. Kolory progowe: zielony poniżej 60%, pomarańczowy przy 60–85%, czerwony powyżej 85%.

Streaming ze spinnerem braille. Tekst streamuje się z płynnym przejściem — spinner braille podczas myślenia, następnie renderowanie Markdown na żywo.

Wzmianki @file z uzupełnianiem tab. Wpisz @src/ i uzyskaj autouzupełnianie plików do włączenia w kontekst.

Trwała pamięć

Agent utrzymuje plik MEMORY.md — trwałe notatki, które przetrwają między sesjami:

agent = create_deep_agent(include_memory=True)
# Agent can call: read_memory, write_memory, update_memory
# MEMORY.md auto-injected into system prompt (first 200 lines)

W CLI użyj /remember, aby zapisać preferencje: “always use pytest, never use unittest.” W następnej sesji agent już to wie. Ten sam wzorzec co pamięć Claude Code, z tą samą automatyczną injekcją 200 linii.

Kluczowe wnioski

• Deep agenty to wzorzec, nie produkt — Claude Code udowodnił architekturę, ale nie potrzebujesz zamkniętego narzędzia, żeby ją zbudować
• Modularność wygrywa — 5 pakietów, które się komponują vs 1 monolit oznacza, że możesz podmienić dowolną warstwę bez przepisywania wszystkiego
• Checkpointy zmieniają przepływ pracy — traktowanie sesji agenta jak gałęzi git (zapisz, cofnij, rozgałęź) czyni asystentów kodowania AI dramatycznie bardziej użytecznymi
• CLI to interfejs — do zadań związanych z kodowaniem, agent terminalowy wygrywa z oknem czatu za każdym razem

Wypróbuj: pydantic-deepagents na GitHub — pip install pydantic-deep[cli]