Files

Apple c552199eed chore: organize documentation structure for monorepo

- Create /docs structure (microdao, daarion, agents)
- Organize 61 cursor technical docs
- Add README files for each category
- Copy key documents to public categories
- Add GitHub setup instructions and scripts

2025-11-15 04:08:35 -08:00

12 KiB

Raw Blame History

37 — Agent Tools & Plugins Specification (MicroDAO)

Докладна специфікація інструментів агентів, категорій безпеки, API-викликів, plugins lifecycle, capability-кодів, sandbox-контрактів та інтеграції через DAARION Tool Fabric

1. Purpose & Scope

Документ визначає:

повний список підтримуваних інструментів (tools),
категорії інструментів за рівнями безпеки,
правила використання,
Plugins API (розширюваність),
інтерфейс між агентом та Tool Proxy,
capability-коди,
сповіщення / події,
обмеження (timeouts, rate limits, isolation),
як підключаються інструменти DAARION Platforms (EnergyUnion, GREENFOOD, Water Union),
як працюють інструменти в confidential mode.

2. Architectural Overview

Agent → Sandbox Runtime → Tool Proxy → Internal Services → DB/NATS

Ключові компоненти:

Tool Proxy — єдина точка доступу агентів до інструментів.
PDP — перевіряє tool.<name>.invoke.
Sandbox — обмежує ресурси.
Plugins API — дозволяє додавати нові інструменти без ризиків.

3. Tool Security Categories

Інструменти діляться на 4 категорії:

3.1 Category A — Safe Tools (default-enabled)

Не мають доступу до зовнішньої мережі, не можуть виконувати код.

Tool	Capability	Опис
math	tool.math.invoke	базові обчислення
text	tool.text.invoke	форматування тексту
memory	tool.memory.invoke	створення коротких summary
embeddings	tool.embeddings.invoke	генерація embedding'ів
calendar	tool.calendar.invoke	маніпуляції з датами/таймзонами

3.2 Category B — Controlled Tools (internal-only)

Працюють тільки через internal APIs.

Tool	Capability	Доступ
search-lite	tool.search.invoke	внутрішній пошук
browser-lite	tool.browser_lite.invoke	обмежений перегляд HTML (без JS)
file	tool.file.invoke	читання з internal storage
project	tool.project.invoke	створення/оновлення проектів
task	tool.task.invoke	створення/оновлення задач

3.3 Category C — Sensitive Tools (restricted)

Вимагають додаткових capability.

Tool	Capability	Опис
router	tool.router.invoke	взаємодія з DAARWIZZ Router
llm	tool.llm.invoke	прямі виклики LLM (через токен-квоти)
agent	tool.agent.invoke	виклик іншого агента
data.query	tool.data_query.invoke	запити до структурованих даних

3.4 Category D — Critical Tools (governance-only)

Потребують схвалення Governance.

Tool	Capability	Ризик
browser-full	tool.browser_full.invoke	доступ до інтернету
external_api	tool.external_api.invoke	сторонні API
chain	tool.chain.invoke	ончейн-транзакції
platform	tool.platform.invoke	доступ до платформ DAARION (energy/food/water)

4. Tool Capability Model

Кожен інструмент має capability:

tool.<name>.invoke

При запуску:

Agent Runtime → Tool Proxy → PDP(authorize)

Якщо capability відсутній → deny.

5. Tool Execution Contract

5.1 Request Format

{
  "tool": "browser_lite",
  "args": {
    "url": "...",
    "max_bytes": 200000
  },
  "context": {
    "agent_run_id": "ar_123",
    "team_id": "t_555"
  }
}

5.2 Response Format

{
  "ok": true,
  "output": "... sanitized result ...",
  "tokens_used": 123,
  "cost_1t": 0.00002
}

6. Tool Proxy Rules

6.1 All Calls Go Through Proxy

Агент не має прямого доступу до:

внутрішніх сервісів,
БД,
зовнішнього інтернету.

6.2 PDP Check

Перед кожним викликом:

PDP(action=tool.<name>.invoke)

6.3 Usage Accounting

Tool Proxy інкрементує usage:

tokens (LLM),
compute units,
tool invocations per day.

7. Timeouts & Limits per Category

Category	Timeout	Rate Limit	Notes
A	1–2s	high	безпечні
B	1–3s	medium	тільки internal
C	3–5s	low	квоти/обмеження
D	5–10s	very low	governance-only

8. Plugins API (Extensible Tools)

Plugins дозволяють стороннім розробникам або платформам додавати нові інструменти.

8.1 Plugin Manifest

{
  "name": "greenfood.order",
  "version": "1.0.0",
  "entry": "plugin.js",
  "capabilities": [
    "tool.greenfood.order.invoke"
  ],
  "permissions": {
    "network": false,
    "filesystem": false,
    "internal_api": ["greenfood"]
  }
}

Allowed fields:

name
version
entry
capabilities
permissions

8.2 Plugin Execution Flow

Agent → Tool Proxy → Plugin Runtime → Internal Service

Plugin Runtime:

запускається в окремому mini-sandbox,
має read-only FS,
немає network,
отримує контекст:
- agent_run_id,
- team_id,
- capability list.

8.3 Plugin Security Model

Plugins НЕ отримують plaintext повідомлень.
Plugins НЕ бачать user session.
Plugins НЕ можуть:
- запускати shell,
- читати файл-систему,
- робити сторонні HTTP-запити.

9. Built-in Tools (Full List)

9.2 Internal Tools (Category B)

project
task
file.storage
search-lite
browser-lite

9.3 Advanced Tools (Category C)

llm
router
agent
data.query

9.4 Platform Tools (Category D)

platform.energy
platform.food
platform.water
chain (controlled by Wallet)
external_api (disabled by default)

10. Platform Tool Contracts (EnergyUnion, GREENFOOD)

10.1 GREENFOOD Tool

tool.greenfood.order.invoke

Allow:

створення замовлення,
перегляд інвентарю продуктів.

Deny:

змінювати ціни,
модифікувати склад.

Input:

{
  "tool":"greenfood.order",
  "args": { "product_id":"...", "qty":1 }
}

Output:

{
  "order_id": "...",
  "status":"created"
}

10.2 EnergyUnion Tool

tool.energy.meter.read