Metadata-Version: 2.4
Name: tongcell
Version: 0.1.0
Summary: 多智能体系统框架
Requires-Python: >=3.13
Requires-Dist: dacite>=1.9.2
Provides-Extra: a2a
Requires-Dist: a2a-sdk; extra == 'a2a'
Provides-Extra: draw
Requires-Dist: pygraphviz>=1.14; extra == 'draw'
Provides-Extra: network
Requires-Dist: grpcio-status>=1.75.0; extra == 'network'
Requires-Dist: tongcellpb; extra == 'network'
Provides-Extra: pydantic
Requires-Dist: pydantic>=2.12.3; extra == 'pydantic'
Description-Content-Type: text/markdown

# tongcell
一个面向开发者的多智能体框架

## 特性(core)
**Actor**：Runtime的基本调度单元，能够处理所接收到的消息。Actor可以是一个有智能性的Agent，也可以是一个没有任何智能性的单元。  
**Runtime**：Actor的容器，负责管理Actor的运行，及Actor间的通信。  

### 动态编排
- Actor由Runtime按需动态创建，Actor的生命周期由Runtime管理。Actor数量无需提前确定，而是在运行过程中动态变化。
- Actor的下游由Actor自身动态决定，无需提前确定。

### 消息驱动
- Actor不直接调用其它Actor，而是通过消息和ActorId/TopcId来通信，Actor相互独立不耦合。
- Actor并发运行。每个Actor都有自己的消息循环，接收到消息后可以立即进行处理。

### 多种通信方式
提供了3种Actor间通信方式：
- 点对点异步通信（send）：消息发送后即返回，无需等待对方处理。
- 点对点同步通信（request）：同步等待对方处理完消息并返回结果。
- 发布订阅（publish）：实现Actor间的解耦，消息发送方无需提前知晓消息接收方。

### 无痛迁移到分布式架构
Actor既可以在本地运行（LocalRuntime），也可以分布式运行在不同的机器上（NetworkRuntime）。
- Actor寻址。Actor间通信时只需要知道对方的ActorId，对方Actor在本地运行或是在远程机器上运行对其是透明的。Runtime会根据ActorId自动勋执导Actor的位置，并将消息送达。
- Actor身份对等。NetworkRuntime不同节点（Peer）间的通信是双向的，无论Actor是运行在client peer上，还是server peer上，其身份都是对等的，既可以接收消息，也可以发送消息。
- 支持多种消息格式。NetworkRuntime支持dataclass、pydantic model、protobuf 3种格式。Actor可以选用任一消息格式或者混用多种消息格式。
- Runtime类型对Actor透明。在LocalRuntime下开发的Actor，可以不经任何修改，直接迁移到NetworkRuntime中进行分布式部署。

## 构建
```bash
# 如果toncellpb依赖通过tool.uv.sources.path映射到了本地，tongcellpb协议更新后，需要重新安装tongcellpb包
# uv sync --reinstall-package tongcellpb
# build前运行下单元测试
# uv run pytest
uv build
```

```bash
# 如果需要画图功能，需要额外安装以下库
apt-get install graphviz graphviz-dev
```

## 快速上手
`examples`目录下有大量的例子供参考。阅读这些例子，对理解SDK种的抽象概念和基础用法会有非常大的帮助。

```bash
uv run examples/core/fib.py

# round robin 模式示例
export OPENAI_API_KEY=xxx
export OPENAI_BASE_URL=xxx
export OPENAI_MODEL=xxx
uv run examples/platform/round_robin_example.py

# swarm 模式示例
uv run examples/platform/swarm_example.py
```