ocuil/akasha-public

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 — 더 간단함, 프로토 컴파일 불필요)

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');

원시 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}

Auth 헤더: 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 명령어로 시스템 프롬프트 업데이트
• 연결 확인 (헬스 → 쓰기 → 읽기 → 삭제)
• 작업 메모리는 TTL을 사용하여 자동 만료