ftai-agent-core 0.3.0

Core library for FtAi Agent Hub clients: protocol, connection management, and reconnection

ftai-agent-core

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

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

• ftai-langchain — LangChain / LangGraph 通用适配器
• ftai-deep-agent — DeepAgent 瘦包装

安装

uv add ftai-agent-core

模块结构

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

编写自定义 Adapter

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

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)