SDK quickstart

The Agent SDK solves the repeated work of calling a model, carrying conversation history, parsing streaming events, and wiring application tools into every product. It gives Python and TypeScript developers one Agent runtime with persistent sessions, streaming, tools, and MCP support.

This is the recommended starting path: install the SDK, bind a ChatSession to a business user ID, and stream an answer without manually rebuilding the conversation context on every request.

This page starts with iztro-ziwei-v3. For a concrete event decision, use iztro-qimen-v3. See Models for model selection, input requirements, and result boundaries.

Both models use the faster non-thinking path by default. For a comprehensive report or difficult multi-evidence judgment, use the Agents SDK's native ModelSettings.reasoning / modelSettings.reasoning with effort: "high". See Model settings.

1. Install

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_..."

The SDK factories read ZIWEI_API_KEY automatically. Keep it in your backend environment or secret manager; never expose it in browser code.

On PowerShell, set the same variable with $env:ZIWEI_API_KEY="sk_ziwei_...".

2. Why use ChatSession

ChatSession keeps a conversation associated with your application user. Pass your own stable external_user_id—for example, the ID from your users table—and you can find that user's sessions without copying chart data or conversation history into every request.

The same identifier lets your backend manage the user's conversations: list sessions, open one session, read its messages, edit or resend a message, and apply retention or deletion policies. See ChatSession management for the complete lifecycle.

3. Stream a complete ChatSession request

The example below is intentionally self-contained. It creates or resumes a session for user_42, sends one request, and prints the streamed text as it arrives.

Python

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

PROMPT = "I was born on 1990-12-21 at 13:00, female. Please analyze my relationship and marriage timing from 2026 to 2028."

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("\nSession:", session.session_id)

asyncio.run(main())

TypeScript

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

const agent = iztroZiweiAgent();
const session = new ChatSession({externalUserId: 'user_42'});
const result = await run(agent, 'I was born on 1990-12-21 at 13:00, female. Please analyze my relationship and marriage timing from 2026 to 2028.', {session, stream: true});
for await (const event of result) {
  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('Conversation:', session.sessionId);

The next pages explain the same pieces separately: ChatSession, streaming, non-streaming, tools, and MCP.

Real example: 01_hello_ziwei.py

This is the complete first-run example from the Python SDK repository. It supplies birth details, runs the Agent, reports the Iztro chart tool, and prints the full reading. The recorded output is shown inline below.

Source: examples/01_hello_ziwei.py.

Prompt used for this run

I was born on 1990-12-21 at 13:00, female. Please give me a detailed reading of my personality and life pattern.

Complete recorded output

Loading recorded output…