Akasha — エージェント共有認知ファブリック (SDK、ドキュメント、エージェントスキル)

Akasha エージェントオンボーディングスキル

新しいエージェントをAkashaに接続するための完全ガイド。

ステップ1: 認証情報を取得する

オプションA: APIキー（エージェント向け推奨）

管理者にダッシュボードまたはAPI経由でキーを作成してもらいます:

curl -sk -X POST "$AKASHA_URL/api/v1/admin/keys" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-new-agent",
    "namespaces": ["memory/working/my-new-agent/**", "memory/semantic/**", "memory/episodic/**"],
    "role": "agent"
  }'

返された key を保存してください。一度しか表示されません。

オプションB: JWTトークン（ユーザーセッション）

TOKEN=$(curl -sk -X POST "$AKASHA_URL/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"my-user","password":"my-password"}' \
  | python3 -c "import json,sys; print(json.load(sys.stdin)['token'])")

ステップ2: SDKを選択する

Python（gRPC — パフォーマンス推奨）

pip install akasha-client

from akasha import AkashaClient

with AkashaClient("localhost:50051") as client:
    # 書き込み
    client.put("memory/working/my-agent/status", {"state": "ready"})
    
    # 読み取り
    record = client.get("memory/working/my-agent/status")
    print(record.value)  # {"state": "ready"}
    
    # クエリ
    results = client.query("memory/working/**")

Python（HTTP — シンプル、protobufコンパイル不要）

from akasha import AkashaHttpClient

client = AkashaHttpClient(
    "https://localhost:7777",
    verify_ssl=False  # 自己署名TLS証明書用
)
client.login("my-user", "my-password")
# またはAPIキーを使用:
# client = AkashaHttpClient("https://...", api_key="ak_my-agent_xxx")

client.put("memory/working/my-agent/status", {"state": "ready"})

Node.js

const { AkashaClient } = require('@akasha/client');

const client = new AkashaClient({
  address: 'localhost:50051',
  // またはHTTP用:
  // url: 'https://localhost:7777',
  // token: 'ak_my-agent_xxx'
});

await client.put('memory/working/my-agent/status', { state: 'ready' });
const record = await client.get('memory/working/my-agent/status');

Raw HTTP（任意の言語）

# エージェントの環境変数に設定
export AKASHA_URL="https://localhost:7777"
export AKASHA_TOKEN="ak_my-agent_xxxxxxxxxxxx"

# 書き込み
curl -sk -X POST "$AKASHA_URL/api/v1/records/memory/working/my-agent/status" \
  -H "Authorization: Bearer $AKASHA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": {"state": "ready"}}'

# 読み取り
curl -sk "$AKASHA_URL/api/v1/records/memory/working/my-agent/status" \
  -H "Authorization: Bearer $AKASHA_TOKEN"

ステップ3: 名前空間戦略を定義する

エージェントの役割に基づいてパス構造を選択:

リサーチエージェント

memory/working/<agent-id>/task          ← 現在のタスクコンテキスト
memory/episodic/research/<finding-id>   ← 生の調査結果
memory/semantic/research/<insight>      ← 確認済み知識

コードエージェント

memory/working/<agent-id>/context       ← 現在のコードコンテキスト
memory/procedural/coding/<pattern>      ← 再利用可能なコードパターン
memory/semantic/architecture/<decision> ← アーキテクチャ決定

モニタリングエージェント

memory/working/<agent-id>/alerts        ← アクティブなアラート
memory/episodic/incidents/<incident-id> ← インシデントタイムライン
memory/semantic/runbooks/<procedure>    ← 実証済みの修復手順

マルチエージェントチーム

shared/                                 ← チーム全体の共有状態
  ├── config/<setting>                  ← 共有設定
  ├── tasks/<task-id>                   ← タスク割り当て
  └── results/<task-id>                 ← タスク結果

memory/working/<agent-id>/              ← 各エージェントのプライベートスクラッチパッド

ステップ4: システムプロンプトにAkashaを追加する

エージェントのシステムプロンプトに次のブロックを追加（ドメインに合わせて調整）:

## 共有メモリ (Akasha)

あなたは共有知識ベースに接続されています。記憶と共有に使用してください。

### 書き込み: POST /api/v1/records/<path>
  Body: {"value": <json>, "ttl_secs": <optional>}

### 読み取り: GET /api/v1/records/<path>

### 検索: GET /api/v1/query?pattern=<glob-pattern>

### シグナル: POST /api/v1/pheromones/<trail>
  Body: {"signal_type":"discovery","message":"...","intensity":0.8}

認証ヘッダー: Authorization: Bearer <your-token>
ベースURL: <your-akasha-url>

一時的な状態には作業メモリ（ttl_secs）を使用してください。
確認済み知識にはセマンティックメモリを使用してください。
新しい作業を開始する前にシグナルを確認してください。

ステップ5: 接続を確認する

# ヘルスチェック（認証不要）
curl -sk $AKASHA_URL/api/v1/health

# 書き込みテスト
curl -sk -X POST "$AKASHA_URL/api/v1/records/test/hello" \
  -H "Authorization: Bearer $AKASHA_TOKEN" \
  -d '{"value": {"message": "Agent connected!"}}'

# 読み取りテスト
curl -sk "$AKASHA_URL/api/v1/records/test/hello" \
  -H "Authorization: Bearer $AKASHA_TOKEN"

# クリーンアップ
curl -sk -X DELETE "$AKASHA_URL/api/v1/records/test/hello" \
  -H "Authorization: Bearer $AKASHA_TOKEN"

チェックリスト

• APIキーまたはJWTトークンを取得
• SDKをインストール（Python/Node/HTTP）
• 名前空間戦略を定義
• システムプロンプトにAkashaの指示を追加
• 接続を確認（health → write → read → delete）
• 作業メモリにTTLを設定して自動期限切れを有効化