Agents SDK Models: Flow/DAG 機能評価と拡張設計 (v3) - Refinire
Author: kitfactory
Description: 複数のLLMプロバイダーに対応した統一インターフェースライブラリ

コンテンツにスキップ

# Agents SDK Models: Flow/DAG 機能評価と拡張設計 (v3)

# Step / Flow API リファレンス

本ドキュメントでは agents‑sdk‑models における `Step` と `Flow` が提供する主要メソッド・属性を一覧表で整理する。CLI でも GUI でも利用しやすいよう 同期ユーティリティ と 非同期タスク の両系統を含める。

## 1. Step インターフェース

メンバー | 種別 | シグネチャ / 型 | 説明
--- | --- | --- | ---
`name` | 属性 | `str` | ステップ識別名（DSL で参照）
`run` | `async def` | `run(user_input: str \| None, ctx: Context) -> Context` | ステップを 1 回実行し、新しい `Context` を返す。必要に応じ `ctx.next_label` を更新する。

> 実装例: `UserInputStep`, `ConditionStep`, `AgentPipeline` など。

## 2. Flow クラス

### 🚀 新機能：拡張されたコンストラクタ

Flowクラスは3つの方法で作成できるようになりました：

    # 1. 単一ステップ（最もシンプル！）
    flow = Flow(steps=gen_agent)

    # 2. シーケンシャルステップ（自動接続！）
    flow = Flow(steps=[step1, step2, step3])

    # 3. 従来方式（複雑なフロー用）
    flow = Flow(start="step1", steps={"step1": step1, "step2": step2})

メソッド / 属性 | 同期 / 非同期 | シグネチャ | 役割・備考
--- | --- | --- | ---
`__init__` | sync | `Flow(start=None, steps=Dict[str,Step]|List[Step]|Step)` | 拡張！ 辞書・リスト・単一ステップに対応。リストは自動接続、単一は直接実行。
`context` | 属性 | `Context` | 現在の共有状態・履歴などを保持。
`finished` | 属性 | `bool` | `ctx.next_label is None` で `True`。
`run` | async | `run(initial_input: str | None = None) -> Context`
`run_loop` | async | `run_loop() -> None` | 非同期タスクとして常駐。`UserInputStep` に当たると一時停止し、`feed()` 待ち。GUI / WebSocket と相性が良い。
`next_prompt` | sync | `next_prompt() -> str | None`
`feed` | sync / async | `feed(user_input: str) -> None` | ユーザー入力を `ctx.last_user_input` に格納し、`run_loop` を再開させる。
`step` | sync | `step() -> None` | 非同期を使わず 1 ステップだけ同期的に進める。LLM 呼び出し中はブロック。

### ライフサイクル図（概要）

1. `flow.run_loop()` をタスク起動
2. Flow が `UserInputStep` に到達 ⇒ `ctx.awaiting_prompt` に質問文設定 & `return`
3. アプリ側 → `next_prompt()` で取得 → ユーザーに提示
4. `feed()` で回答注入 → `ctx.waiter.set()` ⇒ `run_loop` 再開
5. `ctx.next_label is None` になったらフロー終了、`flow.finished == True`。

## 3. 🎯 新しい超シンプル使用例

新しいFlowコンストラクタを使った超シンプルな例：

    from agents_sdk_models import create_simple_gen_agent, Flow, DebugStep

    # 1. 単一ステップ（たった1行！）
    gen_agent = create_simple_gen_agent("assistant", "親切に回答します", "gpt-4o-mini")
    flow = Flow(steps=gen_agent)
    result = await flow.run(input_data="こんにちは")
    print(result.shared_state["assistant_result"])

    # 2. シーケンシャルステップ（自動接続！）
    reviewer = create_simple_gen_agent("reviewer", "回答をレビューします", "gpt-4o")
    flow = Flow(steps=[gen_agent, reviewer, DebugStep("done", "完了")])
    result = await flow.run(input_data="AIについて教えて")

    # 3. 複数GenAgent（マルチエージェント）
    idea_gen = create_simple_gen_agent("idea", "アイデア生成", "gpt-4o-mini")
    writer = create_simple_gen_agent("writer", "記事執筆", "gpt-4o")
    editor = create_simple_gen_agent("editor", "編集・校正", "claude-3-5-sonnet-latest")

    flow = Flow(steps=[idea_gen, writer, editor])  # 自動でアイデア→執筆→編集
    result = await flow.run(input_data="AI技術について")

## 4. 同期 vs 非同期 利用例

### 非同期 GUI / WebSocket

    flow = Flow(...)
    asyncio.create_task(flow.run_loop())
    ...
    prompt = await flow.context.awaiting_prompt_event.wait()
    await websocket.send_json({"prompt": prompt})
    ...
    await flow.feed(user_input_from_client)

### 同期 CLI

    flow = Flow(...)
    while not flow.finished:
        if (prompt := flow.next_prompt()):
            user = input(prompt + "> ")
            flow.feed(user)
        else:
            flow.step()  # LLM 呼び出しなど
    print(flow.context.artifacts)

これで Step / Flow の API 一覧と運用パターンが俯瞰できる。詳しい `Context` フィールド定義や型変換ユーティリティは Agents Sdk Context Design キャンバスを参照。

## 4. Flow/Step 機能の評価

### 4.1 強み

- 宣言的 StepによるDAG 定義 — 学習コストが低い
- Pipeline 再利用性 — 既存資産をそのままステップとして活用
- 暗黙の END — ゴールステップ省略で最短構成
- 動的ルーティング — `router_fn` による条件分岐が容易

### 4.2 課題

- 大規模化で可読性低下 — 辞書定義が肥大
- 共有状態ガイド不足 — Context 設計が必須
- ユーザー入力ステップ未整備 — 標準型を追加すべき
- 並列実行未対応 — Fork/Join 構文の拡充が必要

### 4.3 総評

80% ユースケースを最短コードで解決するライト級だが、課題克服で大規模・対話ワークフローへ拡張可能。

## 5. Flow 拡張設計提案

### 5.1 設計目標

1. 宣言的 DSL × 可視性
2. ユーザー入力ステップ の標準化
3. 型安全 Context 共有
4. 非同期・並列 サポート
5. オブザーバビリティ 組み込み

### 5.2 共通インターフェース `Step`

    from typing import Protocol, runtime_checkable

    @runtime_checkable
    class Step(Protocol):
        name: str
        async def run(self, user_input: str | None, ctx: "Context") -> "Context":
            ...

`AgentPipeline` も同シグネチャで適合。

### 5.3 代表的 Step 実装

`UserInputStep`, `ConditionStep`, `ForkStep`, `JoinStep` など（詳細は前版と同等）。

### 5.4 DSL 使用例

    flow = Flow(
        start="welcome",
        steps={
            "welcome": UserInputStep("welcome", prompt="ご用件を入力してください"),
            "triage": triage_agent_pipeline,   # Step 実装済み
            "need_approval": ConditionStep(
                "need_approval",
                cond=lambda ctx: ctx.shared_state.get("need_approval", False),
                if_true="ask_ok", if_false="final"
            ),
            "ask_ok": UserInputStep("ask_ok", prompt="実行してもよろしいですか？(y/n)"),
            "final": response_agent_pipeline,
        },
    )

    # ---------------- 非同期 GUI / API サーバ ----------------
    asyncio.create_task(flow.async_run_loop())
    ...
    prompt = await flow.context.awaiting_prompt_event.wait()
    await websocket.send_json({"prompt": prompt})
    ...
    flow.feed(user_answer)

    # ---------------- 同期 CLI ----------------
    while not flow.finished:
        if (p := flow.next_prompt()):
            flow.feed(input(p + "> "))
        else:
            flow.step()
    print(flow.context.artifacts)

### 5.5 Context

→ 詳細は “Agents Sdk Context Design” キャンバスを参照。

### 5.6 並列実行サポート

構文 | 説明 |
--- | --- | ---
`ForkStep(branches: list[str])` | 指定ステップを async gather で並列起動 |
`JoinStep(join_type="all" | "any")` | `Context` マージ後 `next_label` 設定

### 5.7 GUI / チャット統合

- `flow.async_run_loop()` をバックグラウンドタスク化
- `ctx.io` 抽象で CLI / Web / Bot を統一
- ストリーミング応答は `Step` 内でトークン逐次送信

### 5.8 オブザーバビリティ

- `before_run` / `after_run` フック → OpenTelemetry Span
- `ctx.trace_id` で全 Step 横断の相関 ID

### 5.9 ロードマップ

バージョン | 主要機能
--- | ---
v0.1 | `Step`, `UserInputStep`, `Context`, 直列 Flow, `async_run` / `async_run_loop`
v0.2 | `ConditionStep`, `ForkStep`, `JoinStep`, 並列実行
v0.3 | GUI/チャット I/O アダプタ、OpenTelemetry 連携
v0.4 | Step テンプレート登録、AutoDocs 生成
v1.0 | 安定版リリース、セマンティックバージョニング