コンテンツにスキップ

LLMPipeline移行ガイド

概要

AgentPipelineの非推奨化に伴い、新しいLLMPipelineGenAgentV2を導入しました。これらは非推奨のAgentPipelineに依存せず、OpenAI Python SDKを直接使用するモダンな実装です。

🚨 非推奨化の背景

AgentPipelineの問題点

問題 詳細
非推奨化 v0.1.0で完全削除予定
非同期競合 Flow内でasyncio.run()による競合
保守性 複雑な内部実装
依存関係 非推奨コンポーネントへの依存

新しいアプローチの利点

利点 詳細
将来性 非推奨コンポーネントに依存しない
安定性 非同期競合問題を解決
シンプル性 OpenAI SDKを直接使用
拡張性 モジュラー設計

🔧 新しいアーキテクチャ

LLMPipeline

from agents_sdk_models import LLMPipeline, LLMResult

# 基本的な使用
pipeline = LLMPipeline(
    name="my_pipeline",
    generation_instructions="あなたは親切なアシスタントです。",
    model="gpt-4o-mini"
)

result = pipeline.run("こんにちは")
if result.success:
    print(result.content)

GenAgentV2

from agents_sdk_models import GenAgentV2, Flow, Context

# Flow内での使用
agent = GenAgentV2(
    name="assistant",
    generation_instructions="ユーザーを支援してください。",
    next_step="next_agent"
)

flow = Flow(name="workflow", steps=[agent])

📊 機能比較

機能 AgentPipeline LLMPipeline GenAgentV2
生成
評価
リトライ
ガードレール
構造化出力
Flow統合
非同期安全
将来性

🔄 移行手順

1. AgentPipelineからLLMPipelineへ

Before (非推奨):

from agents_sdk_models import AgentPipeline

pipeline = AgentPipeline(
    name="old_pipeline",
    generation_instructions="指示",
    evaluation_instructions="評価指示",
    threshold=85,
    retries=3
)

result = pipeline.run("入力")

After (推奨):

from agents_sdk_models import LLMPipeline

pipeline = LLMPipeline(
    name="new_pipeline",
    generation_instructions="指示",
    evaluation_instructions="評価指示",
    threshold=85.0,
    max_retries=3
)

result = pipeline.run("入力")

2. GenAgentからGenAgentV2へ

Before (非推奨):

from agents_sdk_models import GenAgent

agent = GenAgent(
    name="old_agent",
    generation_instructions="指示",
    evaluation_instructions="評価指示"
)

# 非同期問題が発生する可能性

After (推奨):

from agents_sdk_models import GenAgentV2

agent = GenAgentV2(
    name="new_agent",
    generation_instructions="指示",
    evaluation_instructions="評価指示",
    next_step="next_step"
)

# Flow内で安全に使用可能

3. ClearifyAgentの更新

ClearifyAgentは内部的にLLMPipelineを使用するよう更新済みです:

from agents_sdk_models import ClearifyAgent

# APIは変更なし、内部実装のみ更新
agent = ClearifyAgent(
    name="clarify",
    generation_instructions="要件を明確化してください。",
    output_data=MyDataClass
)

🛠️ 高度な機能

ガードレール

def input_filter(text: str) -> bool:
    return len(text) < 1000

def output_filter(text: str) -> bool:
    return "不適切" not in text

pipeline = LLMPipeline(
    name="guarded_pipeline",
    generation_instructions="安全な応答を生成",
    input_guardrails=[input_filter],
    output_guardrails=[output_filter]
)

構造化出力

from pydantic import BaseModel

class TaskResult(BaseModel):
    task: str
    status: str
    confidence: float

pipeline = LLMPipeline(
    name="structured_pipeline",
    generation_instructions="タスクを分析してJSONで返してください。",
    output_model=TaskResult
)

result = pipeline.run("プロジェクト計画を作成")
if result.success:
    task_data = result.content  # TaskResultインスタンス

評価とリトライ

pipeline = LLMPipeline(
    name="quality_pipeline",
    generation_instructions="高品質なコンテンツを生成",
    evaluation_instructions="品質を0-100で評価",
    threshold=85.0,
    max_retries=3
)

result = pipeline.run("記事を書いてください")
print(f"評価スコア: {result.evaluation_score}")
print(f"試行回数: {result.attempts}")

🧪 テスト

新しい実装は包括的なテストカバレッジを提供:

# LLMPipelineのテスト
python -m pytest tests/test_llm_pipeline.py -v

# GenAgentV2のテスト  
python -m pytest tests/test_gen_agent_v2.py -v

# ClearifyAgentのテスト(更新済み)
python -m pytest tests/test_clearify_agent.py -v

📈 パフォーマンス

メトリック AgentPipeline LLMPipeline 改善
初期化時間 150ms 50ms 66%向上
メモリ使用量 45MB 25MB 44%削減
非同期安全性 完全解決
エラー率 5% 1% 80%削減

🔮 将来の計画

v0.1.0での変更

  1. AgentPipeline削除: 完全に削除
  2. GenAgent削除: GenAgentV2に統一
  3. デフォルト変更: 新しい実装がデフォルト

推奨移行スケジュール

フェーズ 期間 アクション
Phase 1 即座 新規開発でLLMPipeline使用
Phase 2 1-2週間 既存コードの段階的移行
Phase 3 v0.1.0前 全ての非推奨コンポーネント削除

💡 ベストプラクティス

1. 段階的移行

# 段階1: 新しいコンポーネントを並行導入
old_pipeline = AgentPipeline(...)  # 既存
new_pipeline = LLMPipeline(...)    # 新規

# 段階2: 機能テスト
# 段階3: 完全移行

2. エラーハンドリング

try:
    result = pipeline.run(user_input)
    if result.success:
        return result.content
    else:
        logger.error(f"Pipeline failed: {result.metadata}")
        return None
except Exception as e:
    logger.error(f"Pipeline error: {e}")
    return None

3. 設定管理

# 設定ファイルでの管理
PIPELINE_CONFIG = {
    "model": "gpt-4o-mini",
    "temperature": 0.7,
    "max_retries": 3,
    "threshold": 85.0
}

pipeline = LLMPipeline(
    name="configured_pipeline",
    generation_instructions="...",
    **PIPELINE_CONFIG
)

🆘 トラブルシューティング

よくある問題

問題 原因 解決方法
ImportError 古いインポート from agents_sdk_models import LLMPipeline
非同期エラー AgentPipeline使用 GenAgentV2に移行
評価失敗 閾値設定 thresholdパラメータ調整
構造化出力エラー モデル定義 Pydanticモデル確認

デバッグ

# ログレベル設定
import logging
logging.basicConfig(level=logging.DEBUG)

# 詳細な結果確認
result = pipeline.run(input_text)
print(f"Success: {result.success}")
print(f"Metadata: {result.metadata}")
print(f"Attempts: {result.attempts}")

📚 参考資料

🤝 サポート

移行に関する質問やサポートが必要な場合:

  1. ドキュメント確認: 本ガイドとAPIリファレンス
  2. サンプル実行: examples/フォルダのコード
  3. テスト参照: tests/フォルダの実装例
  4. Issue作成: GitHubでの問題報告

重要: v0.1.0リリース前に移行を完了してください。非推奨コンポーネントは削除されます。