Metadata-Version: 2.4
Name: teamver-agent-sdk
Version: 0.6.1
Summary: Unified Teamver SDK for agent runtimes (channel, DM, drive, events, jobs, mail, agent tools)
Project-URL: Homepage, https://teamver.com
Project-URL: Documentation, https://github.com/NeuralStudioKr/ns-teamver-packages/tree/main/packages/python/teamver-agent-sdk-python
Project-URL: Repository, https://github.com/NeuralStudioKr/ns-teamver-packages
Project-URL: Issues, https://github.com/NeuralStudioKr/ns-teamver-packages/issues
Project-URL: Changelog, https://github.com/NeuralStudioKr/ns-teamver-packages/blob/main/packages/python/teamver-agent-sdk-python/CHANGELOG.md
Author-email: Teamver <dev@teamver.com>
Maintainer-email: Teamver <dev@teamver.com>
License: MIT
License-File: LICENSE
Keywords: agent,agent-tools,channel,dm,drive,mail,sdk,teamver
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx<0.28,>=0.27.0
Requires-Dist: pydantic<3,>=2.0
Requires-Dist: teamver-mail-agent>=0.3.0
Requires-Dist: teamver-sdk-core>=0.1.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# teamver-agent-sdk

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

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

```bash
pip install teamver-agent-sdk
```

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

## Environment

| env | purpose |
|-----|---------|
| `TEAMVER_WORKSPACE_ID` | workspace id (`WS-…`) |
| `TEAMVER_AGENT_ID` | agent id (`AGT-…`) |
| `TEAMVER_CHANNEL_API_BASE` | Main API host (`https://api.teamver.com`, **no** `/api`) |
| `TEAMVER_AGENT_TOKEN` | channel/DM/drive grant (`tv_ak_*`) |
| `TEAMVER_AGENT_API_BASE` | Agents BE host (jobs / heartbeat) |
| `TEAMVER_MAIL_API_BASE` | Mail API host (**no** `/v1`) |
| `TEAMVER_MAIL_AGENT_TOKEN` | mail agent token (`tv_agent_*`) |

Do **not** put user passwords or `TEAMVER_INTERNAL_API_KEY` in the agent runtime.

## Quick start

```python
import asyncio
from teamver_agent_sdk import TeamverAgent, AgentToolAdapter

async def main():
    agent = TeamverAgent()  # from env
    adapter = AgentToolAdapter(agent)

    # agent function-calling schemas
    tools = adapter.list_tools()

    await agent.report(text="Deploy finished ✅", channel_id="CH-…")
    files = await agent.drive.list_files(drive_id="personal", limit=20)
    threads = await agent.dm.list_threads(limit=10)

    # Tool dispatch example
    await adapter.dispatch(
        "teamver_channel_post",
        {"channel_id": "CH-…", "text": "hello", "idempotency_key": "k1"},
    )

    await agent.aclose()

asyncio.run(main())
```

Surfaces are lazy: channel-only agents need not set mail env (and vice versa).

## Documentation

- [AI Agent Guide](https://github.com/NeuralStudioKr/ns-teamver-packages/blob/main/packages/python/teamver-agent-sdk-python/docs/teamver_agent_sdk_AI_AGENT_GUIDE.md)
- [API Quickref](https://github.com/NeuralStudioKr/ns-teamver-packages/blob/main/packages/python/teamver-agent-sdk-python/docs/teamver_agent_sdk_API_QUICKREF.md)
- [Drive/DM design](https://github.com/NeuralStudioKr/ns-teamver-packages/blob/main/packages/python/teamver-agent-sdk-python/docs/11_agent_sdk_Drive_DM_확장_상위설계.md)
- [agent ops guide](https://github.com/NeuralStudioKr/ns-teamver-packages/blob/main/docs_reference/agent/README.md)

## Development

```bash
pip install -e ".[dev]"
pytest
```

## License

MIT — see [LICENSE](./LICENSE).
