Metadata-Version: 2.4
Name: ftai-agent-core
Version: 0.3.0
Summary: Core library for FtAi Agent Hub clients: protocol, connection management, and reconnection
Requires-Python: >=3.12
Requires-Dist: websockets>=13.0
Description-Content-Type: text/markdown

# ftai-agent-core

FtAi Agent Hub 的核心库 —— 协议定义、WebSocket 连接管理、认证、自动重连、人机交互机制。

**这是一个基础包**，通常不直接使用，而是由上层 adapter 包依赖：

- [`ftai-langchain`](../langchain/) — LangChain / LangGraph 通用适配器
- [`ftai-deep-agent`](../deep-agent/) — DeepAgent 瘦包装

## 安装

```bash
uv add ftai-agent-core
```

## 模块结构

```
ftai_agent_core/
├── protocol.py   # 协议常量、JSON 编解码、消息构建函数（纯函数，无 I/O）
├── client.py     # BaseAgentHubClient 抽象基类
└── errors.py     # AuthError 异常
```

## 编写自定义 Adapter

继承 `BaseAgentHubClient`，实现 `_process_chat()` 方法：

```python
from ftai_agent_core import BaseAgentHubClient
from ftai_agent_core import protocol


class MyClient(BaseAgentHubClient):
    async def _process_chat(self, request_id: str, messages: list[dict]) -> None:
        # 1. 将 OpenAI 格式的 messages 转换为你的框架格式
        # 2. 流式调用你的 Agent
        # 3. 通过 self._send() 发送响应
        for chunk in my_agent.stream(messages):
            await self._send(protocol.stream_text(request_id, chunk))
        # base class 会自动发送 message_end
```

`BaseAgentHubClient` 已内置：

| 能力 | 说明 |
|------|------|
| 认证 | WebSocket 连接后自动发送 `auth`，处理 `auth_ok` / `auth_error` |
| 自动重连 | 指数退避（2s → 4s → ... → 60s），认证成功后重置 |
| 并发聊天 | 每个 `chat_request` 独立 `asyncio.Task`，互不阻塞 |
| 取消 | 收到 `cancel` 时自动 `task.cancel()` |
| 人机交互 | `self._request_hil(prompt)` / `self.human_in_loop_tool` |
| 发送序列化 | `asyncio.Lock` 保证并发 task 的 WebSocket 写入不交叉 |
| 错误处理 | 异常自动发送 `error` 帧，取消自动发送 `message_end(cancel)` |
