pip install -e /path/to/zapry-agents-sdk-python

from zapry_agents_sdk import ZapryAgent, AgentConfig

config = AgentConfig.from_env()
bot = ZapryAgent(config)

@bot.command("start")
async def start(update, context):
    await update.message.reply_text("Hello from Zapry Bot!")

@bot.command("help")
async def help_cmd(update, context):
    await update.message.reply_text("Available commands: /start, /help")

bot.run()

# handlers/tarot.py
from zapry_agents_sdk.helpers import HandlerRegistry

tarot = HandlerRegistry()

@tarot.command("tarot")
async def tarot_command(update, context):
    await update.message.reply_text("🎴 抽牌中...")

@tarot.callback("^reveal_card_")
async def reveal_card(update, context):
    ...

# main.py
from zapry_agents_sdk import ZapryAgent, AgentConfig
from handlers.tarot import tarot

bot = ZapryAgent(AgentConfig.from_env())
bot.register(tarot)
bot.run()

from zapry_agents_sdk import ProactiveScheduler

# 创建调度器（60 秒轮询一次）
scheduler = ProactiveScheduler(
    interval=60,
    send_fn=my_send_message,  # async def send(user_id, text)
)

# 方式 1：装饰器注册触发器
@scheduler.trigger("daily_greeting")
async def check_greeting(ctx):
    if ctx.now.hour == 12 and ctx.now.minute <= 30:
        return ["user_001", "user_002"]  # 需要发送的用户
    return []

@check_greeting.message
async def greeting_msg(ctx, user_id):
    return f"中午好~ 今天状态怎么样？"

# 方式 2：编程式注册
scheduler.add_trigger("birthday", check_fn, message_fn)

# 生命周期
await scheduler.start()   # 启动后台轮询
await scheduler.stop()    # 停止

# 用户级开关
await scheduler.enable_user("user_001")
await scheduler.disable_user("user_001")

from zapry_agents_sdk import FeedbackDetector, build_preference_prompt

detector = FeedbackDetector()

# 检测反馈信号
result = detector.detect("太长了，说重点")
# result.matched => True
# result.changes => {"style": "concise"}

# 一步完成检测 + 更新偏好
prefs = {"style": "balanced"}
await detector.detect_and_adapt("user_001", "太长了", prefs)
# prefs => {"style": "concise", "updated_at": "..."}

# 自定义关键词（默认中文，可覆盖）
detector.add_pattern("language", "english", ["speak english", "in english"])

# 偏好注入 AI prompt
prompt = build_preference_prompt({"style": "concise", "tone": "casual"})
# => "回复风格偏好：\n这位用户偏好简洁的回复..."

bot = ZapryAgent(config)
scheduler = ProactiveScheduler(interval=60)
detector = FeedbackDetector()

@bot.on_post_init
async def post_init(app):
    scheduler.send_fn = lambda uid, text: app.bot.send_message(int(uid), text)
    await scheduler.start()

@bot.on_post_shutdown
async def shutdown(app):
    await scheduler.stop()

@bot.message()
async def on_message(update, context):
    user_id = str(update.effective_user.id)
    # 在回复后异步检测反馈
    result = await detector.detect_and_adapt(user_id, update.message.text, user_prefs)

from zapry_agents_sdk import ZapryAgent, AgentConfig

bot = ZapryAgent(AgentConfig.from_env())

# 注册中间件（按顺序包裹）
async def timer_middleware(ctx, next_fn):
    import time
    start = time.time()
    await next_fn()  # 调用下一层
    print(f"耗时: {time.time() - start:.3f}s")

async def auth_middleware(ctx, next_fn):
    if not is_authorized(ctx.update):
        return  # 不调用 next_fn → 拦截
    ctx.extra["role"] = "admin"
    await next_fn()

bot.use(timer_middleware)
bot.use(auth_middleware)

from zapry_agents_sdk.tools import tool, ToolRegistry

# @tool 装饰器自动从 type hints + docstring 生成 JSON schema
@tool
async def get_weather(city: str, unit: str = "celsius") -> str:
    """获取指定城市的当前天气。

    Args:
        city: 城市名称
        unit: 温度单位
    """
    return f"{city}: 25°C, 晴"

registry = ToolRegistry()
registry.register(get_weather)

# 导出 schema
schema = registry.to_json_schema()
openai_tools = registry.to_openai_schema()

# 执行工具
result = await registry.execute("get_weather", {"city": "上海"})

from zapry_agents_sdk.tools.openai_adapter import OpenAIToolAdapter

adapter = OpenAIToolAdapter(registry)

# 1. 获取 tools 参数
tools_param = adapter.to_openai_tools()

# 2. 调用 OpenAI
response = await client.chat.completions.create(
    model="gpt-4o", messages=messages, tools=tools_param,
)

# 3. 处理 tool_calls
if response.choices[0].message.tool_calls:
    results = await adapter.handle_tool_calls(
        response.choices[0].message.tool_calls
    )
    messages.extend(adapter.results_to_messages(results))

from zapry_agents_sdk.memory import MemorySession, InMemoryStore, SQLiteMemoryStore

# 创建 session（agent+user 隔离）
session = MemorySession(
    agent_id="my_agent",
    user_id="user_123",
    store=SQLiteMemoryStore("memory.db"),  # 或 InMemoryStore()
)

# 加载所有记忆
ctx = await session.load()
# ctx.short_term  → 对话历史
# ctx.long_term   → 用户档案
# ctx.working     → 会话临时数据

# 添加消息（自动持久化 + 缓冲区管理）
await session.add_message("user", "我今年25岁，在上海做程序员")
await session.add_message("assistant", "了解了~")

# 获取可注入 LLM 的 prompt
prompt = session.format_for_prompt()

# 自动记忆提取（需设置 extractor）
from zapry_agents_sdk.memory import LLMMemoryExtractor
session.extractor = LLMMemoryExtractor(llm_fn=my_llm_call)
await session.extract_if_needed()

# 手动更新长期记忆
await session.update_long_term({"basic_info": {"age": 25}})

# 清空
await session.clear_history()  # 只清对话
await session.clear_all()      # 清除所有

async def memory_middleware(ctx, next_fn):
    session = MemorySession("bot", get_user_id(ctx.update), store)
    await session.load()
    ctx.extra["session"] = session
    await next_fn()
    await session.extract_if_needed()

bot.use(memory_middleware)

from zapry_agents_sdk.agent import AgentLoop
from zapry_agents_sdk.tools import ToolRegistry, tool

@tool
async def get_weather(city: str) -> str:
    """获取天气。"""
    return f"{city}: 25°C"

registry = ToolRegistry()
registry.register(get_weather)

async def my_llm(messages, tools=None):
    response = await openai_client.chat.completions.create(
        model="gpt-4o", messages=messages, tools=tools,
    )
    return response.choices[0].message

loop = AgentLoop(
    llm_fn=my_llm,
    tool_registry=registry,
    system_prompt="You are a helpful assistant.",
    max_turns=10,  # 防止无限循环
)

result = await loop.run("上海天气怎么样？")
print(result.final_output)       # "上海现在 25°C，晴天。"
print(result.tool_calls_count)   # 1
print(result.total_turns)        # 2 (1次工具调用 + 1次最终回答)
print(result.stopped_reason)     # "completed"

from zapry_agents_sdk.agent import AgentHooks

hooks = AgentHooks(
    on_llm_start=lambda turn, msgs: print(f"Turn {turn}: calling LLM..."),
    on_tool_start=lambda name, args: print(f"Calling tool: {name}"),
    on_tool_end=lambda name, result, err: print(f"Tool result: {result}"),
    on_error=lambda e: print(f"Error: {e}"),
)
loop = AgentLoop(llm_fn=my_llm, tool_registry=registry, hooks=hooks)

session = MemorySession("my_agent", "user_123", store)
ctx = await session.load()

result = await loop.run(
    "记住我的生日是10月15日",
    conversation_history=await session.short_term.get_history_dicts(),
    extra_context=session.format_for_prompt(),
)

from zapry_agents_sdk import MCPManager, MCPServerConfig, ToolRegistry, AgentLoop

mcp = MCPManager()

# 连接 MCP 服务器
await mcp.add_server(MCPServerConfig(
    name="filesystem",
    transport="stdio",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
))

await mcp.add_server(MCPServerConfig(
    name="search",
    transport="http",
    url="https://mcp.example.com/search",
    headers={"Authorization": "Bearer xxx"},
))

# 注入到 ToolRegistry（与本地工具共存）
registry = ToolRegistry()
registry.register(my_local_tool)   # 你的本地工具
mcp.inject_tools(registry)         # MCP 工具自动添加

# AgentLoop 透明使用 MCP 工具
loop = AgentLoop(llm_fn=my_llm, tool_registry=registry)
result = await loop.run("读取 /tmp/data.txt")

# 清理
await mcp.disconnect_all()

await mcp.add_server(MCPServerConfig(
    name="filesystem",
    transport="stdio",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    allowed_tools=["read_*", "list_*"],   # 只允许读/列表工具
    blocked_tools=["write_*", "delete_*"], # 阻止危险工具
    max_tools=10,                           # 限制上下文大小
))

zapry-agents-sdk/
├── pyproject.toml
├── README.md
├── zapry_agents_sdk/
│   ├── __init__.py          # 包入口
│   ├── core/
│   │   ├── bot.py           # ZapryAgent 主类（含 middleware 集成）
│   │   ├── config.py        # AgentConfig 配置
│   │   └── middleware.py    # Middleware 洋葱管道
│   ├── helpers/
│   │   └── handler_registry.py  # Handler 注册装饰器 & Registry
│   ├── proactive/
│   │   ├── scheduler.py     # ProactiveScheduler 主动消息调度器
│   │   └── feedback.py      # FeedbackDetector 反馈检测 & 偏好注入
│   ├── tools/
│   │   ├── registry.py      # @tool 装饰器 + ToolRegistry + schema 生成
│   │   └── openai_adapter.py # OpenAI function calling 适配器
│   ├── agent/
│   │   └── loop.py          # AgentLoop ReAct 推理循环（含 Guardrails + Tracing）
│   ├── guardrails/
│   │   └── engine.py        # Guardrails 安全护栏 + Tripwire 机制
│   ├── tracing/
│   │   └── engine.py        # 结构化 Span 追踪系统
│   ├── mcp/
│   │   ├── __init__.py      # MCP 模块入口
│   │   ├── config.py        # MCPServerConfig, 工具过滤
│   │   ├── transport.py     # HTTPTransport, StdioTransport, InProcessTransport
│   │   ├── protocol.py      # JSON-RPC 2.0, MCPClient, MCPError
│   │   ├── converter.py     # MCP tool → SDK ToolDef 转换
│   │   └── manager.py       # MCPManager 统一管理
│   ├── memory/
│   │   ├── session.py       # MemorySession 便捷 API
│   │   ├── store.py         # MemoryStore Protocol + InMemoryStore
│   │   ├── store_sqlite.py  # SQLiteMemoryStore
│   │   ├── short_term.py    # ShortTermMemory 对话历史
│   │   ├── long_term.py     # LongTermMemory 用户档案
│   │   ├── working.py       # WorkingMemory 会话临时数据
│   │   ├── buffer.py        # ConversationBuffer 对话缓冲
│   │   ├── extractor.py     # MemoryExtractor + LLMMemoryExtractor
│   │   ├── formatter.py     # prompt 注入格式化
│   │   └── types.py         # 数据类型定义
│   └── utils/
│       ├── telegram_compat.py   # Zapry 兼容层
│       └── logger.py            # 日志工具
└── tests/
    ├── test_compat.py       # 兼容层测试
    ├── test_proactive.py    # 主动触发 & 反馈检测测试（44 项）
    ├── test_middleware.py   # Middleware 管道测试（9 项）
    ├── test_tools.py        # Tool Calling + OpenAI 适配器测试（32 项）
    ├── test_memory.py       # Memory 框架全量测试（55 项）
    ├── test_agent_loop.py   # AgentLoop 测试（17 项）
    └── test_guardrails.py   # Guardrails + Tracing 测试（28 项）