SDK 快速开始

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

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

本页使用 iztro-ziwei-v3。四个公开模型都支持单次请求和多轮对话。客户资料和提示词示例见场景与模型。

iztro-ziwei-v3 和 iztro-qimen-v3 默认开启思考，对应的 -fast 模型默认关闭。可通过 Agents SDK 的 ModelSettings.reasoning / modelSettings.reasoning 覆盖默认值：high 开启思考，none 关闭。详见模型设置。

1. 安装

Python

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

TypeScript

npm install openai-iztro-agents @openai/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 创建或恢复会话，发送一个请求，并在文字生成时立即输出。

Python

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())

TypeScript

import {run} from '@openai/agents';
import {ChatSession, isIztroToolEvent, iztroZiweiAgent} from 'openai-iztro-agents';

const prompt = '我出生于1990年6月15日上午10点，男性。请给我一份完整的个人性格与人生格局解读。';
const agent = iztroZiweiAgent();
const session = new ChatSession({externalUserId: 'user_42'});
const streamed = await run(agent, prompt, {session, stream: true});
for await (const event of streamed) {
  if (event.type !== 'raw_model_stream_event') continue;
  const data = event.data as unknown;
  if (isIztroToolEvent(data)) process.stdout.write(`\n🔮 iztro computed: ${data.tools.join(', ')}\n`);
  else if (event.data.type === 'output_text_delta') process.stdout.write(event.data.delta);
}
console.log('会话 ID：', session.sessionId);

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

模型调用函数

调用其他模型时，使用对应函数：

模型	Python	TypeScript
iztro-ziwei-v3	iztro_ziwei_agent(...)	iztroZiweiAgent({...})
iztro-qimen-v3	iztro_qimen_agent(...)	iztroQimenAgent({...})
iztro-ziwei-v3-fast	iztro_ziwei_fast_agent(...)	iztroZiweiFastAgent({...})
iztro-qimen-v3-fast	iztro_qimen_fast_agent(...)	iztroQimenFastAgent({...})

真实示例：01_hello_ziwei.py

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

源码：examples/01_hello_ziwei.py。

本次运行使用的 Prompt

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

完整真实输出

正在加载真实输出…