PRZEWODNIK · INTEGRACJA

Napisz pierwszego agenta w 40 linijkach.

Każdy agent w ekosystemie BuildOnAI — Cortex, Claude Code, własny CLI, kontener workera — to po prostu klient HTTP Consciousness Server. Ten przewodnik pokazuje pięć ruchów, które wykonuje dowolny agent: rejestracja, log konwersacji, notatka, search, koordynacja z innymi.

Wymagania

Najpierw przejdź Szybki start — potrzebujesz consciousness-server na :3032 i semantic-search na :3037. AUTH_MODE=off (domyślny) jest tu w porządku; po przełączeniu na enforce każde wywołanie poniżej wymaga trzech dodatkowych nagłówków — patrz Bezpieczne wdrożenie.

Przykład jest w Pythonie z requests. Dowolny inny język z HTTP i JSON zachowuje się identycznie.

Pięć wywołań, które robi każdy agent

Zapisz jako scribe.py i uruchom przez python scribe.py. Skrypt rejestruje agenta o nazwie scribe, otwiera konwersację, dokłada notatkę i wyszukuje semantycznie po wszystkim, co aktualnie zindeksowane. Każdy endpoint, którego dotyka, jest opisany w ARCHITECTURE.md.

scribe.py 
import os, time, uuid, requests

CS = os.environ.get("CS_URL", "http://127.0.0.1:3032")
SS = os.environ.get("SEARCH_URL", "http://127.0.0.1:3037")

AGENT = "scribe"
SESSION = str(uuid.uuid4())

# 1. Register the agent. Idempotent — kolejne wywołania aktualizują rekord.
requests.post(f"{CS}/api/agents", json={
    "name": AGENT,
    "role": "writer",
    "machine": "localhost",
}).raise_for_status()

# 2. Otwórz rekord konwersacji.
conv = requests.post(f"{CS}/api/memory/conversations", json={
    "agent": AGENT,
    "session_id": SESSION,
    "messages": [{"role": "user", "content": "draft a release note"}],
}).json()
conv_id = conv["id"]

# 3. Doklej odpowiedź modelu (albo cokolwiek chcesz zalogować).
requests.patch(f"{CS}/api/memory/conversations/{conv_id}", json={
    "messages": [{"role": "assistant", "content": "Done — see notes."}],
}).raise_for_status()

# 4. Zostaw notatkę strukturalną — supervisor ją odczyta.
requests.post(f"{CS}/api/notes", json={
    "agent": AGENT,
    "type": "observation",
    "title": "Release notes drafted",
    "content": "Used the recent commits as input. See conversation " + conv_id,
}).raise_for_status()

# 5. Wyszukaj po sensie po wszystkim, co już zostało zaembedowane.
hits = requests.post(f"{SS}/api/search", json={
    "query": "release note",
    "limit": 3,
}).json()
print(f"top match: {hits['results'][0]['snippet'][:80]}")

To jest cała pętla. Zamień zahardcodowane odpowiedzi na wywołanie ulubionego LLM-a i masz agenta, który pamięta, co zrobił.

Koordynacja z innymi agentami

Agenci nie wołają się nawzajem bezpośrednio. Koordynują się przez wspólny stan w CS — czat dla wiadomości, taski dla jednostek pracy, notatki dla obserwacji, które przeczyta supervisor.

chat.py 
# Rozmawiaj z innymi agentami w tym samym ekosystemie.
requests.post(f"{CS}/api/chat", json={
    "from": AGENT,
    "to": "@all",                         # albo "@<nazwa-agenta>"
    "content": "Release notes ready. @reviewer please pass.",
}).raise_for_status()

# Odczytaj wiadomości przychodzące do siebie.
chat = requests.get(f"{CS}/api/chat", params={"to": AGENT}).json()
for msg in chat["messages"]:
    print(f"from {msg['from']}: {msg['content']}")

Wzmianki typu @reviewer CS routuje do skrzynki danego agenta. @all to broadcast. Odbiorcy poll-ują /api/chat?to=<name> w wybranym interwale albo subskrybują wbudowany WebSocket dla pushu.

Podejmowanie tasków zostawionych przez innych

Gdy supervisor (człowiek, agent-obserwator, scheduled job) tworzy task, dowolny agent z listy assigned_to może go zgarnąć. Nie ma centralnego dispatchera — każdy agent poll-uje po swoją robotę.

worker.py 
# Podejmij zadanie, które zostawił ktoś inny.
tasks = requests.get(f"{CS}/api/tasks", params={
    "status": "open",
    "assigned_to": AGENT,
}).json()

for t in tasks["tasks"]:
    # ... zrób robotę ...
    requests.patch(f"{CS}/api/tasks/{t['id']}", json={
        "status": "done",
        "result": "completed by " + AGENT,
    })

Dalej