miti-agent-sdk

Connect third-party agents (Hermes, OpenClaw, Claude Code, etc.) to the Miti IM platform.

Installation

pip install miti-agent-sdk

Quick Start

from miti_agent_sdk import MitiAgent

agent = MitiAgent(
    app_id="cli_xxx",
    app_secret="secret_xxx",
)

# 单聊消息
@agent.on_message
async def handle(event):
    user_text = event.event.message.content.get("text", "")
    await event.reply(f"收到：{user_text}")

# 群 @ 消息
@agent.on_group_at
async def handle_group(event):
    text = event.event.message.content.get("text", "")
    await event.reply(f"群收到：{text}")

agent.run()

SDK 内部自动处理：Token 获取/刷新、WebSocket 保活、指数退避重连。

环境配置

base_url 按以下优先级决定（先找到先用）：

app_id / app_secret 可在 Miti App 的 我的 → 设置 → 智能体管理 → 连接智能体 创建后获取。

大多数场景下不需要配置任何东西，SDK 自动连接正式环境。

本地开发调试时，通过环境变量指向本地 appserver 即可，无需改业务代码：

export MITI_API_BASE_URL="http://localhost:10006/chat"

也可以在初始化时显式传入：

agent = MitiAgent(
    app_id="cli_xxx",
    app_secret="secret_xxx",
    base_url="http://localhost:10006/chat",
)

拉取历史记录

@agent.on_message
async def handle(event):
    history = await agent.get_history(
        event.event.message.conversation_id, limit=10
    )
    # history: list[HistoryMessage]  each has .role and .content

日志 & 问题排查

SDK 使用 Python 标准 logging 模块，logger 层级为 miti_agent_sdk.*。

快速开启日志

import miti_agent_sdk

# INFO 级别：token 获取/刷新、WebSocket 连接/断开/重连、事件收发、消息发送
miti_agent_sdk.enable_logging()

# DEBUG 级别：额外输出每次 HTTP 请求 URL/参数、自动刷新 sleep 倒计时
miti_agent_sdk.enable_logging(logging.DEBUG)

日志输出到 stderr（默认），格式示例：

2026-06-18 18:00:01 [miti_agent_sdk.auth] INFO token acquired, expires_in=7200s
2026-06-18 18:00:01 [miti_agent_sdk.gateway] INFO connecting to wss://www.miti.chat/chat/agent/gateway
2026-06-18 18:00:02 [miti_agent_sdk.gateway] INFO gateway connected
2026-06-18 18:00:05 [miti_agent_sdk.gateway] INFO event received: type=im.message.receive id=evt-xxx
2026-06-18 18:00:05 [miti_agent_sdk.message] INFO send_message success: target=user-abc message_id=msg-xxx

日志存储

SDK 本身不写日志文件。日志的最终存储取决于宿主进程：

排查常见问题

安全注意事项

日志安全

SDK 自身不会在日志中输出 app_secret 或 access_token。但如果你开启了 aiohttp 的 trace/debug 日志（如 AIOHTTP_TRACE=1），HTTP 请求体会被底层框架 打印出来，其中包含 app_secret。生产环境请勿开启 aiohttp trace 日志。

凭证内存存储

app_secret 和 access_token 在 SDK 运行期间以明文存储在进程内存中。 这是 Python SDK 的通用模式（与飞书 SDK、Slack SDK 一致），无法避免。 请确保：

• 不要在多租户共享环境中运行 agent 进程
• 不要将进程 memory dump 输出到不安全的位置
• 进程退出后凭证自动释放，无需手动清理

TLS 要求

SDK 强制要求 base_url 使用 https://（对应 WebSocket wss://）。 本地开发调试时 localhost / 127.0.0.1 可使用 http://，其他地址会被拒绝。

Requirements

• Python 3.9+
• aiohttp >= 3.9
• websockets >= 12.0