Arhitektura — AgentCTL

Pregled

Slojevita arhitektura

Ports-and-adapters. Svaki sloj zavisi samo od interfejsa ispod. Ne pričamo o spaghetti kodu.

CLI sloj

main · run · chat · validate · init · config · TUI · REPL

Engine

Sesija · korak · dispatch alata · auto-nastavak · strukturirani izlaz

LLM

Alati

MCP

Konfig

Portovi i adapteri

ConfigSource · Secrets (OS Keychain) · StateStore · MemoryStore

Jezgro

Engine loop

Svaka korisnička poruka prolazi kroz isti ciklus. Engine ne zna ništa o provajderu — vidi samo događaje.

Korisnička poruka

Session.Step()

Provider.Stream()

Petlja događaja

EventText

prosleđuj u terminal

EventToolCall

skupi pozive

EventUsage

broj tokena

EventDone

proveri stop razlog

EventError

vrati grešku

end_turn

gotovo, vrati

tool_use

izvrši → opet

max_tokens

nastavi → opet

Provajderi

Sami se registruju, bez vezivanja

Provajderi se registruju preko init() + llm.Register(). Engine zove llm.Resolve("provider/model") i dobija Provider interfejs. Ništa komplikovano, ako čitaš.

llm.Resolve("provider/model")

Registar provajdera

Anthropic

Custom SSE

OpenAI

OpenAI SSE

Ollama

NDJSON

Gemini

Compat

Alibaba

Compat

LiteLLM

Compat

Svi LLM klijenti su stdlib-only — net/http, bufio, encoding/json. Bez SDK zavisnosti. Gemini, Alibaba i LiteLLM koriste WithCompat() koji isključi OpenAI specifične štoseve. Klin bez čekića.

Alati

Dispatch alata i bezbednost

Svaki poziv alata prolazi kroz registar. Pisanje fajlova traži potvrdu korisnika. Undo vraća poslednje pisanje. Bez „pa ja sam mislio“.

Model traži poziv alata

tools.Registry.Run()

Ugrađeni alati

shell

fs_read

fs_write

⚠️ potvrdi

fs_list

git

test_run

delegate

MCP alati

Rezultat → nazad u model kao tool_result

Delegacija

Hub-and-spoke pattern

Orkestrator delegira specijalistima. Spoke vraćaju strukturirani JSON. Više delegacija ide paralelno. Kao tim koji radi, ne kao tim na sastanku.

Korisnički zahtev

Hub agent

Razlaže zadatak, delegira, sintetizuje

spoke-coder

svoj model + alati

spoke-reviewer

read-only

spoke-planner

samo planira

Strukturirani JSON odgovor

{ "answer": "...",
  "sources": [{ file, summary }],
  "confidence": "high",
  "caveats": ["..."] }

Hub sintetizuje sa citatima

[spoke-coder: main.go:10-25] ...

MCP

MCP integracija — tok

Agent referencira MCP server po imenu. Menadžer ga pokrene, rukuje se, otkrije alate i name-spejsuje ih. Bez ručne pelene.

mcp: [jira, confluence]

u frontmatter-u agenta

mcp.Manager.Open()

Pokreni proces

stdio transport

→

JSON-RPC handshake

initialize + initialized

→

tools/list

otkrij alate

Name-spejsovani alati (preko ToolAdapter-a)

jira__get_issue

jira__search

jira__add_comment

confluence__get_page

confluence__search

confluence__update_page

Spojeni u tools.Registry uz ugrađene alate

Strukturirani izlaz

Provajderski-nativna JSON kontrola

Kad response_schema postoji u frontmatter-u, engine forsira validan JSON preko nativnog mehanizma svakog provajdera. Bez parsiranja regex-om kao u 2018-oj.

response_schema: { type: object, ... }

u frontmatter-u agenta

Anthropic

response-tool + forced tool_choice

OpenAI

json_schema strict mode

Ollama

format polje

Engine bafera ceo odgovor (bez stream-a)

Izvuci "answer"

prikaz korisniku

Sačuvaj ceo JSON

hub vidi strukturu

Poređenje

Kako AgentCTL stoji prema ostalima

Karakteristika	AgentCTL	Cursor	GitHub Copilot	Aider	Continue
Interfejs	CLI / TUI	IDE (VS Code fork)	IDE plugin	CLI	IDE plugin
Definicija agenta	Markdown fajlovi	Ugrađeno	Ugrađeno	Config flagovi	JSON config
Više provajdera	✓ 6 provajdera	~ 3	✗ samo OpenAI	✓ Mnogo	✓ Mnogo
Lokalni modeli	✓ Ollama	~ Ograničeno	✗	✓	✓
MCP podrška	✓ Stdio	✗	✗	✗	✓
Sub-agenti	✓ Hub-and-spoke	✗	✗	✗	✗
Strukturirani izlaz	✓ JSON schema	✗	✗	✗	✗
Potvrda za pisanje	✓ Uvek	✓ Diff prikaz	~ Auto	✓	✓
Verzionisanje	✓ Git ugrađen	~ IDE git	~ IDE git	✓ Auto-commit	✗
Veličina binary-a	7.8 MB	~500 MB	Plugin	pip install	Plugin
Zavisnosti	✓ Nula	Electron	VS Code	Python	VS Code
Cena	Besplatno (+ API)	$20/mes	$10/mes	Besplatno (+ API)	Besplatno (+ API)

Principi

Dizajnerske odluke

Engine ne zna za provajdera

Bez specifičnog provajderskog koda u engine-u ili alatima. Menjaj backend bez diranja jezgra. Onako kako treba.

Stdlib-only LLM klijenti

Bez SDK zavisnosti. Svaki HTTP poziv je obični net/http. Lako se debaguje, lako se forka.

Ključevi u OS keychain-u

macOS Keychain ili Linux libsecret. Nikad u config fajlovima. Nikad u plain tekstu. Nikad u javnom git logu.

MD fajlovi su istina

Agenti, veštine, alati, MCP serveri — sve definisano u Markdownu sa YAML frontmatter-om. Bez UI klikača.

Shell umesto native klijenata

K8s, Terraform, Helm preko shell-a — bez client-go, bez verzionog vezivanja, binary ostaje mali.

Portovi za proširivost

ConfigSource, Secrets, StateStore interfejsi. Menjaš implementaciju bez diranja engine-a.