跳到主要内容

SDK 快速开始

接入模型时，应用通常需要重复处理模型请求、会话历史、流式事件和业务工具。Agent SDK 将这些工作统一为 Python 和 TypeScript 共用的 Agent 运行时，并提供持久会话、流式输出、工具与 MCP 支持。

推荐流程是：安装 SDK，用 ChatSession 绑定业务用户，再用流式调用将结果实时返回给用户。这样不必在每次请求中自行拼装历史上下文。

本页先使用 iztro-ziwei-v3。如果要判断一件具体事件，请改用 iztro-qimen-v3。模型选择、输入要求和结果边界见模型。

两个模型默认走更快的非思考路径。完整报告或需要多项证据交叉判断的复杂问题，请使用 Agents SDK 原生的 ModelSettings.reasoning / modelSettings.reasoning，并将 effort 设为 "high"。详见模型设置。

1. 安装​

pip install openai-iztro-agents
export ZIWEI_API_KEY="sk_ziwei_..."

SDK 便捷工厂会自动读取 ZIWEI_API_KEY。请把它保存在后端环境变量或密钥管理器中，绝不能暴露到浏览器代码。

PowerShell 使用 $env:ZIWEI_API_KEY="sk_ziwei_..." 设置同一个变量。

2. 为什么使用 ChatSession​

ChatSession 会把对话与应用中的用户关联。传入你用户表里稳定的 external_user_id 后，就能找到该用户的会话，而无需在每次请求中重复发送命盘数据或完整历史。

同一个标识也让后端可以管理该用户的对话：列出会话、打开一个会话、读取消息，以及执行保留或删除策略。完整生命周期请见 ChatSession 管理。

3. 使用 ChatSession 发起完整流式请求​

下面的示例会为 user_42 创建或恢复会话，发送一个请求，并在文字生成时立即输出。

import asyncio
from agents import Runner
from openai.types.responses import ResponseTextDeltaEvent
from iztro_agents import ChatSession, IztroToolEvent, iztro_ziwei_agent

PROMPT = "我出生于1990年6月15日上午10点，男性。请给我一份完整的个人性格与人生格局解读。"

async def main():
    agent = iztro_ziwei_agent()
    session = ChatSession(external_user_id="user_42")
    result = Runner.run_streamed(agent, PROMPT, session=session)
    async for event in result.stream_events():
        if event.type == "raw_response_event" and isinstance(event.data, IztroToolEvent):
            print(f"\n🔮 iztro computed: {', '.join(event.data.tools)}\n")
        elif event.type == "raw_response_event" and isinstance(event.data, ResponseTextDeltaEvent):
            print(event.data.delta, end="")
    print("\n会话 ID：", session.session_id)

asyncio.run(main())

后续页面会分别讲解 ChatSession、流式输出、非流式调用、工具 与 MCP。

真实示例：01_hello_ziwei.py​

这是 Python SDK 的首次运行示例：提供出生信息，运行 Agent，显示 Iztro 命盘工具，并输出完整解读。下面直接展示与 Prompt 对应的完整真实输出。

源码：examples/01_hello_ziwei.py。

本次运行使用的 Prompt

我出生于1990年6月15日上午10点，男性。请给我一份完整的个人性格与人生格局解读。

完整真实输出

正在加载真实输出…