198 lines
11 KiB
Markdown
198 lines
11 KiB
Markdown
# Балда / Валера — эксплуатация
|
||
|
||
## Расположение
|
||
- Repo: `~/Developer/balda/` (ветка `main`)
|
||
- Code: upstream `normahq/balda` + `feat/zulip-transport` влит, `normahq/norma` v0.0.10
|
||
- **Рабочий compose**: `~/Docker/balda-agent/docker-compose.yaml` → контейнер `balda-agent-valera-1`
|
||
- Config (persistent): `~/Docker/balda-agent/.config/balda/config.yaml`
|
||
- Env: `~/Docker/balda-agent/.env`
|
||
- Owner: `allowed_owners` в config.yaml (статически, `/start owner=` не нужен)
|
||
|
||
## Запуск / рестарт
|
||
|
||
```bash
|
||
cd ~/Docker/balda-agent
|
||
docker-compose restart # без пересборки, только конфиг/env не менялись
|
||
docker-compose up -d # пересоздать контейнер, перечитать .env
|
||
|
||
# Rebuild после изменений в коде:
|
||
cd ~/Docker/claudio-agent && docker-compose build
|
||
docker tag claudio-agent-claudio:latest balda-agent-valera:latest
|
||
cd ~/Docker/claudio-agent && docker-compose up -d
|
||
cd ~/Docker/balda-agent && docker-compose up -d
|
||
```
|
||
|
||
> Валера и Клавдий — **один образ** (`balda-agent-valera`), собирается из одного Dockerfile (`Dockerfile.claudio`). Разница только в конфиге (`config.yaml`) и `.env`, которые монтируются volumes. Сборка идёт из `~/Docker/claudio-agent/` — там есть build секция.
|
||
|
||
## Архитектура получения сообщений
|
||
Валера — **outgoing webhook bot** (bot_type=3). Zulip отправляет webhook только для @mention и DM.
|
||
|
||
- `events_polling.enabled: false` в config.yaml
|
||
- Сообщения приходят только через **outgoing webhook** (webhook_token в .env)
|
||
- После @mention создаётся сессия; последующие сообщения без @mention обрабатываются
|
||
|
||
**После перезапуска**: написать `@Валера <текст>` чтобы создать сессию.
|
||
|
||
## MCP Obsidian — конфиг
|
||
Balda через SSE подключается к obsidian-mcp. **URL обязательно с `/sse`**:
|
||
|
||
```yaml
|
||
runtime:
|
||
mcp_servers:
|
||
obsidian:
|
||
type: sse
|
||
url: http://obsidian-mcp:3101/sse # <-- без /sse → 404 Not Found
|
||
name: obsidian
|
||
```
|
||
|
||
## Контекст (история сообщений)
|
||
**Работает** (на upstream `normahq/balda` с поддержкой hosted LLM agent sessions). ADK inject'ит историю корректно для OpenAI-совместимых провайдеров.
|
||
|
||
Раньше не работало — исправлено в upstream `32e33a8 fix: support hosted MCP toolsets` / `d774c78 fix: use hosted llmagent sessions`.
|
||
|
||
## Проблема: MCP не работают у Валеры (provider: type=openai)
|
||
|
||
### Коренная причина
|
||
hostedagent (`pkg/runtime/hostedagent/`) не поддерживает MCP инструменты.
|
||
`openAIConstructor` в `agentfactory.go` получает `resolvedMCP map[string]agentconfig.MCPServerConfig`,
|
||
но не передаёт их в `hostedagent.Config` — у Config нет поля для MCP.
|
||
`openAIConstructor` вызывает `newHostedAgent(hostedagent.Config{...})` без MCPServers.
|
||
|
||
Фикс: в `hostedagent.Config` добавить `MCPServers map[string]agentconfig.MCPServerConfig`,
|
||
а в `openAIConstructor` передавать `toRuntimeMCPServers(resolvedMCP)`.
|
||
|
||
Важно: hostedagent использует OpenAI-compatible API (не ACP). MCP инструменты нужно
|
||
интегрировать через OpenAI tool_calls — модель шлёт tool_call, код выполняет MCP вызов.
|
||
|
||
## Проблема: MCP не работают у Валеры — попытка фикса
|
||
|
||
### Что было сделано (2026-06-19)
|
||
|
||
#### 1. go.mod
|
||
Добавлен `replace github.com/normahq/norma => ../norma-local` — для локальной разработки.
|
||
|
||
#### 2. hostedagent — добавлена поддержка MCP
|
||
- `pkg/runtime/hostedagent/agent.go`:
|
||
- В Config добавлено `MCPServers map[string]acpagent.MCPServerConfig`
|
||
- Сохранено в `runtimeAgent`
|
||
- В `run()`: после создания модели вызывается `model.SetTools(openAIToolsFromMCPServers(r.MCPServers))`
|
||
|
||
- `pkg/runtime/hostedagent/openai.go`:
|
||
- В `openAIChatRequest` добавлено `Tools []openAIToolDefinition`
|
||
- В `OpenAIModel` добавлены `tools []openAIToolDefinition + `SetTools()`
|
||
- Добавлен `tool_calls` в парсинг ответа (`tool_calls` → content string)
|
||
|
||
#### 3. agentfactory — передача MCP
|
||
- В `openAIConstructor` добавлено `MCPServers: toRuntimeMCPServers(resolvedMCP)` в вызов `newHostedAgent()`
|
||
|
||
#### 4. Dockerfile
|
||
В `Dockerfile.claudio` добавлен `COPY norma-local/ ./norma-local/` — чтобы `replace` работал в контейнере.
|
||
|
||
#### 5. Сборка
|
||
Образ собран и запущен как `balda-agent-valera:latest`.
|
||
|
||
#### 6. Диагностика
|
||
- `mcpServerIDs` приходят корректно: `[balda obsidian fast-rlm]`
|
||
- Добавлен stderr-лог в `agentfactory.go` в `Build()`:
|
||
```go
|
||
fmt.Fprintf(os.Stderr, "BALDA-DEBUG: mcpServerIDs=%v resolvedMCP=%v\n", mcpServerIDs, resolvedMCP)
|
||
```
|
||
- Для просмотра логов нужен `docker logs balda-agent-valera-1 2>&1 | grep BALDA-DEBUG`
|
||
|
||
### Почему не заработало
|
||
Точная причина не установлена — нужно увидеть `resolvedMCP` в логах контейнера. Возможные варианты:
|
||
- `resolveMCPServers` возвращает пустой map
|
||
- `toRuntimeMCPServers` неправильно конвертирует
|
||
- `SetTools` не влияет на уже созданные сообщения в сессии
|
||
|
||
### Что осталось
|
||
1. Прочитать stderr из контейнера: `docker logs balda-agent-valera-1 2>&1 | grep BALDA-DEBUG`
|
||
2. Если `resolvedMCP` пустой — исправлять цепочку resolveMCPServers
|
||
3. Если не пустой — тестировать response с tool_calls в DeepSeek ответе
|
||
|
||
## Диагностика молчания
|
||
|
||
### 1. MCP ошибка: `failed to list MCP tools: failed to connect: Not Found`
|
||
**Причина**: в config.yaml url без `/sse` на конце.
|
||
**Фикс**: `url: http://obsidian-mcp:3101/sse` → `docker-compose restart`.
|
||
|
||
### 2. В логах `command running → command handled` за секунду, без `received provider event`
|
||
**Причина**: стухший embedded NATS. Swarm внутри процесса не доставляет команду до session/task actor'ов.
|
||
**Фикс**: `docker-compose restart` (если не помогло → `up -d`).
|
||
|
||
### 3. Удалён / пустой state.db
|
||
После удаления balda не может зарегистрировать swarm акторы.
|
||
**Фикс**: `rm state.db` и `up -d` (balda создаст заново).
|
||
|
||
### 4. Нет owner
|
||
`handleMessage` выходит при `getOwnerID() == 0`.
|
||
**Фикс**: прописать `allowed_owners` в config.yaml (не нужен `/start owner=`).
|
||
|
||
### 5. stream_only_with_session
|
||
Сообщение в теме без сессии молча дропается.
|
||
**Фикс**: написать `@Валера <текст>` чтобы создать сессию.
|
||
|
||
### 6. Проверить webhook со стороны
|
||
```bash
|
||
curl -X POST http://localhost:8091/zulip/webhook \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"type":"test"}'
|
||
```
|
||
|
||
## Ключевые грабли
|
||
|
||
### OPENAI_BASE_URL — обязательная env var
|
||
Norma не читает `base_url` из config.yaml для `provider: deepseek`. Читает env `OPENAI_BASE_URL`.
|
||
Без неё запросы уходят на `api.openai.com` (401).
|
||
|
||
**В `.env` обязательно:**
|
||
```
|
||
OPENAI_BASE_URL=https://api.deepseek.com/v1
|
||
```
|
||
|
||
### DOCKER_OPTS — пустая строка убивает старт
|
||
Должен быть валидный JSON:
|
||
```
|
||
DOCKER_OPTS={"max_tokens": 2048, "temperature": 0.7}
|
||
```
|
||
|
||
### composerestart vs compose up -d
|
||
- `restart` — не перечитывает `.env`
|
||
- `up -d` — пересоздаёт контейнер с обновлённым `.env`
|
||
|
||
|
||
---
|
||
|
||
## Диагноз: MCP не работают — инструменты не передаются модели
|
||
|
||
**Статус (2026-06-21):** MCP резолвятся, но не вызываются.
|
||
|
||
**Установлено через BALDA-DEBUG:**
|
||
```
|
||
BALDA-DEBUG: mcpServerIDs=[balda obsidian fast-rlm]
|
||
resolvedMCP=map[balda:{http http://127.0.0.1:33545/mcp}
|
||
fast-rlm:{http http://fast-rlm-mcp:3333/mcp}
|
||
obsidian:{sse http://obsidian-mcp:3101/sse}]
|
||
```
|
||
MCP серверы зарезолвлены, тулсеты переданы в `hostedagent.Config`.
|
||
|
||
**Почему не работают:**
|
||
`OpenAIModel.generate()` → `buildChatRequest()` не читает `req.Config.Tools` (поле `genai.GenerateContentConfig`). ADK кладёт инструменты туда, но `buildChatRequest` сериализует только `model`, `messages`, `temperature`, `top_p`, `max_tokens`, `stop`. DeepSeek получает запрос без `tools` → отвечает текстом.
|
||
|
||
**Логи подтверждают:** `function_call_part_count=0` в ответе DeepSeek.
|
||
|
||
**Фикс:** добавить передачу tools в OpenAI запрос и парсинг tool_calls из ответа.
|
||
**Сделано (2026-06-21):** в `openai.go` добавлены:
|
||
- `openAIToolDefinition`, `openAIFunction`, `openAIToolCall` — структуры для API
|
||
- Поле `Tools` в `openAIChatRequest`
|
||
- Функция `openAIToolsFromConfig()` — конвертирует `genai.Tool[]` → OpenAI tool definitions
|
||
- Функция `contentToOpenAI()` — обрабатывает FunctionCall/FunctionResponse из ADK
|
||
- Парсинг `tool_calls` в `parseChatResponse()`
|
||
- **Тесты:** 17 тестов на new функциональность + 3 существующих = все проходят
|
||
|
||
1. Добавить поле `Tools` в `openAIChatRequest` + `openAIToolDefinition`
|
||
2. В `buildChatRequest` читать `req.Config.Tools` → конвертировать в OpenAI tool definitions
|
||
3. В `parseChatResponse` парсить `tool_calls` из ответа (ADK сам выполнит MCP)
|
||
|
||
**Важно:** upstream `norma` v0.0.10 (`bf2b25d`) уже корректно передаёт MCP тулсеты через `agentfactory.hostedToolsets()`. Проблема только в том, что `OpenAIModel` — кастомная реализация, не умеющая прокидывать tools. Если бы использовался Gemini/ACP provider — MCP бы работали.
|