127 lines
3.7 KiB
Markdown
127 lines
3.7 KiB
Markdown
# Przepływ danych i IPC
|
|
|
|
#sympozium #architektura #ipc
|
|
|
|
## Mechanizm IPC
|
|
|
|
Sympozium używa **filesystem-based IPC** - agenty komunikują się z control plane przez pliki JSON w woluminie `/ipc/`:
|
|
|
|
```
|
|
Agent tool pisze JSON → /ipc/<dir>/*.json → fsnotify watcher → NATS publish → Controller
|
|
```
|
|
|
|
### Katalogi IPC
|
|
|
|
| Katalog | Cel | Przykład |
|
|
|---------|-----|---------|
|
|
| `/ipc/tools/` | Wykonanie komend w sidecarze | `execute_command` |
|
|
| `/ipc/messages/` | Wysyłanie wiadomości na kanały | `send_channel_message` |
|
|
| `/ipc/schedules/` | Zarządzanie schedulami | `schedule_task` |
|
|
|
|
## Dlaczego filesystem IPC?
|
|
|
|
### Zalety
|
|
1. **Language-agnostic** - agent mógłby być w Pythonie, Rust, czymkolwiek
|
|
2. **Zero zależności** - agent nie potrzebuje klienta NATS ani żadnego SDK
|
|
3. **Inspekcja** - pliki JSON w woluminie można łatwo debugować
|
|
4. **Prostota** - zapis pliku to najprostsza operacja I/O
|
|
5. **Bezpieczeństwo** - agent nie ma dostępu sieciowego, tylko do woluminu
|
|
|
|
### Jak to działa
|
|
|
|
```
|
|
1. Agent zapisuje /ipc/tools/cmd-12345.json:
|
|
{
|
|
"command": "kubectl get pods",
|
|
"runId": "my-run-123"
|
|
}
|
|
|
|
2. IPC Bridge (sidecar) wykrywa plik via fsnotify
|
|
|
|
3. Bridge publikuje na NATS:
|
|
Topic: tool.exec.request
|
|
Payload: {command, runId, instanceName}
|
|
|
|
4. Skill sidecar (lub controller) odbiera i wykonuje
|
|
|
|
5. Wynik wraca: NATS → IPC Bridge → /ipc/tools/result-12345.json
|
|
|
|
6. Agent czyta wynik z pliku
|
|
```
|
|
|
|
## NATS Topics
|
|
|
|
Kluczowe tematy zdefiniowane w `internal/eventbus/types.go`:
|
|
|
|
### Lifecycle agenta
|
|
- `agent.run.requested` - żądanie nowego runu
|
|
- `agent.run.started` - run rozpoczęty
|
|
- `agent.run.completed` - run zakończony sukcesem
|
|
- `agent.run.failed` - run zakończony błędem
|
|
|
|
### Wiadomości kanałów
|
|
- `channel.message.received` - wiadomość od użytkownika
|
|
- `channel.message.send` - wiadomość do użytkownika
|
|
|
|
### Narzędzia
|
|
- `tool.exec.request` - żądanie wykonania komendy w sidecarze
|
|
- `tool.exec.result` - wynik wykonania
|
|
|
|
### Scheduling
|
|
- `schedule.upsert` - agent sam tworzy/aktualizuje swój schedule
|
|
|
|
## Wbudowane narzędzia agenta
|
|
|
|
Agent-runner ma **7 wbudowanych narzędzi** (`cmd/agent-runner/tools.go`):
|
|
|
|
| Narzędzie | Kategoria | Opis |
|
|
|-----------|-----------|------|
|
|
| `execute_command` | IPC (sidecar) | Uruchamia komendy shell w skill sidecarze |
|
|
| `read_file` | Native | Czyta zawartość pliku |
|
|
| `write_file` | Native | Tworzy/zapisuje pliki |
|
|
| `list_directory` | Native | Listuje zawartość katalogu |
|
|
| `send_channel_message` | IPC (bridge) | Wysyła wiadomości na kanały |
|
|
| `fetch_url` | Native | HTTP GET i zwraca body |
|
|
| `schedule_task` | IPC (bridge) | CRUD na SympoziumSchedule CRDs |
|
|
|
|
### Natywne vs IPC
|
|
|
|
- **Native** - narzędzia wykonywane bezpośrednio w kontenerze agenta
|
|
- **IPC (sidecar)** - narzędzia delegowane do skill sidecara przez IPC bridge
|
|
- **IPC (bridge)** - narzędzia delegowane do controllera przez NATS
|
|
|
|
## Przepływ end-to-end
|
|
|
|
```
|
|
Użytkownik → Telegram
|
|
↓
|
|
Channel Pod (Telegram) → NATS: channel.message.received
|
|
↓
|
|
Channel Router → Tworzy AgentRun CR
|
|
↓
|
|
AgentRun Reconciler → Tworzy Job z kontenerami
|
|
↓
|
|
Agent Container:
|
|
1. Czyta task z /workspace/input/
|
|
2. Czyta skills z /skills/
|
|
3. Czyta memory z /memory/ lub memory API
|
|
4. Wywołuje LLM (OpenAI/Anthropic/etc.)
|
|
5. LLM decyduje o użyciu narzędzia
|
|
6. Agent pisze do /ipc/tools/
|
|
7. IPC Bridge → NATS → Skill Sidecar wykonuje
|
|
8. Wynik wraca → Agent kontynuuje dialog z LLM
|
|
9. Agent pisze wynik do stdout
|
|
↓
|
|
Controller zbiera logi poda
|
|
↓
|
|
Controller → NATS: agent.run.completed
|
|
↓
|
|
Channel Router → NATS: channel.message.send
|
|
↓
|
|
Channel Pod (Telegram) → Użytkownik
|
|
```
|
|
|
|
---
|
|
|
|
Powiązane: [[NATS JetStream - Event Bus]] | [[Cykl życia Agent Pod]] | [[Skill Sidecars i auto-RBAC]]
|