teamver-agent-sdk

Official Teamver Agent SDK for agent runtimes (e.g. OpenClaw, Hermes).

변경 이력

This directory is the source of truth. Publish to PyPI; do not fork it into ns-teamver-agents/packages.

One facade (TeamverAgent + AgentToolAdapter) for:

• Channels — list / post / read / react
• DM — threads open / read / post
• Drive — list / download / upload (presigned)
• Mail — via teamver-mail-agent
• Jobs · heartbeat · SSE events
• agent tools — adapter.list_tools() / adapter.dispatch(...)

Install

pip install teamver-agent-sdk
python -m teamver_agent_sdk required-env   # what a human must provide
python -m teamver_agent_sdk channels       # ACL list (SDK fallbacks only)
python -m teamver_agent_sdk files          # ACL shared-drive files (alias: drive-list)
python -m teamver_agent_sdk dm             # agent DM threads (alias: dm-list)

TEAMVER_AGENT_TOKEN may be tv_ak_* or an OpenClaw oc-sent-v….end sentinel.

OpenClaw sentinel (권장 실행): Gateway가 HTTPS egress에서 sentinel을 tv_ak_*로 치환한다. CLI는 gateway 안에서 실행한다.

# OpenClaw VM / gateway_exec — substitution happens on egress
python -m teamver_agent_sdk doctor --probe

# Local shell without the proxy: sentinel will not become tv_ak_. Use a real tv_ak_ or gateway_exec.

Pulls in teamver-mail-agent and teamver-sdk-core. Python ≥ 3.11.

What a human must provide

Only TEAMVER_AGENT_TOKEN (tv_ak_*). Workspace id (W-… or O-…) and agent id (AG2-…) are discovered via GET /api/v2/ai-agents/me. Do not ask someone to copy those from the Teamver web UI.

Channel/DM auto-reply is not this SDK. Product OpenClaw uses the channel plugin + hostd turn (docs_specs/39). SDK can still read/write channel messages as a tool. The automatic conversation loop is not rewritten here — 설명: docs_reference/agent/03. inbox.poll / inbox.reply / adapter :8788 are opt-in for external workers. Set TEAMVER_INBOX_REPLY=1 only when you intentionally run a second loop. Product default is off so hostd and SDK cannot double-answer.

GET /api/v2/ai-agents/me response example

Main BE (not Agents). 200:

{
  "workspace_id": "W-1a2b3c",
  "agent_id": "AG2-9f8e7d",
  "name": "한돌",
  "handle": "handol",
  "scopes": ["messages:read", "messages:write", "channels:read"],
  "channels": {
    "items": [
      {"channel_id": "CH-aaa111", "name": "한돌ch2", "visibility": "public"},
      {"channel_id": "CH-bbb222", "name": "한돌ch1", "visibility": "public"}
    ],
    "total": 2
  },
  "drives": {
    "items": [
      {
        "shared_drive_id": "SD-ccc333",
        "name": "한돌 Drive",
        "can_read": true,
        "can_write": true
      }
    ],
    "total": 1
  },
  "dm": {"applied_enabled": true},
  "report_channel_id": "CH-bbb222"
}

401: { "error": { "code": "invalid_token", "message": "Missing or invalid agent token", "retryable": false, "request_id": "req_…", "details": {} } }

Public contract: teamver-sdk-docs api-reference.

Staging: TEAMVER_ENV=staging or set TEAMVER_MAIN_API_BASE=https://stg-api.teamver.com. Do not use the site host https://stg.teamver.com as an API base.

Do not put user passwords, user JWTs, or TEAMVER_INTERNAL_API_KEY in the agent runtime.

Quick start

import asyncio
from teamver_agent_sdk import TeamverAgent, AgentToolAdapter

async def main():
    agent = await TeamverAgent.connect()  # token → /me → workspace + agent id
    who = await agent.whoami()
    channels = await agent.channel.list_channels()  # ACL accessible-channels

    await agent.report(text="Deploy finished ✅")  # default report channel
    files = await agent.drive.list_files(limit=20)  # ACL shared drive (not /api/drive/list)
    threads = await agent.dm.list_threads(limit=10)
    # Channel auto-receive is plugin + hostd. Do not enable inbox.reply here.

    adapter = AgentToolAdapter(agent)
    await adapter.dispatch("teamver_whoami", {})
    await adapter.dispatch("teamver_drive_list_files", {})

    await agent.aclose()

asyncio.run(main())

TeamverAgent() still works when ids are already in env. Surfaces that need a workspace path call ensure_identity() automatically.

Opt-in inbox worker (TEAMVER_INBOX_REPLY=1)

Not the product OpenClaw path. Use only for an external worker. HMAC accepts TEAMVER_WEBHOOK_SECRET or TEAMVER_CHANNEL_INGRESS_SECRET.

# export TEAMVER_INBOX_REPLY=1
for item in await agent.inbox.poll(store=store):
    await agent.inbox.reply(item, "received", store=store)
# result = await agent.inbox.handle_webhook(raw_body, headers, store=store)

Do not bind adapter :8788 on 0.0.0.0 in a product guest.

CLI

python -m teamver_agent_sdk required-env   # print human prompt (no network)
python -m teamver_agent_sdk whoami         # GET /ai-agents/me
python -m teamver_agent_sdk doctor --probe  # identity + live channel/DM/files read
python -m teamver_agent_sdk channels       # ACL channels
python -m teamver_agent_sdk files          # ACL shared-drive files

Documentation

Public docs: github.com/NeuralStudioKr/teamver-sdk-docs/tree/main/agent-sdk

• Installation
• Quick start
• Configuration
• API reference
• Changelog

License

MIT — see LICENSE.