# Python SDK 使用指南

**客户端 SDK：** `gateway/client/python/`

## 文档维护规范

0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
1. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
2. **简洁快照，日志分离** - 只记录已确认的使用方式

---

## 概述

Python SDK 供外部 Agent 调用 Gateway HTTP API。

**适用场景：**
- 运行在不同机器的 Agent
- 使用其他 Agent 框架的 Agent

**不适用场景：**
- 和 Gateway 运行在同一台机器的内部 Agent（应直接调用 Core 层）

---

## 安装

```bash
pip install gateway-client
```

---

## 基本使用

### 创建客户端

```python
from gateway.client.python import GatewayClient

client = GatewayClient("http://gateway-host:8000")
```

### 查询对话列表

```python
conversations = client.list_conversations()
```

### 获取消息历史

```python
messages = client.get_messages(conversation_id)
```

### 发送消息

```python
client.send_message(conversation_id, text="Hello!")
```

---

## 模块结构

```
gateway/client/python/
├── client.py    # GatewayClient 主类
├── tools.py     # 工具函数
└── cli.py       # CLI 工具
```

---

## 相关文档

- [需求规划](../requirements.md)：外部 Agent 接入需求
- [架构设计](../architecture.md)：Client SDK 在整体架构中的位置
- [API 文档](../api/)：HTTP API 参考