ライブコーディングエージェント観察

一時停止・ロールバック・分岐を備えたリアルタイム観察でコーディングエージェントの作業を見守ります。ローカルモデル向けのOllama、Anthropic API、Claude Agent SDKの3つのバックエンドに対応しています。

v2.4.0の新機能

静的なトレースのアノテーションから分かるのは、エージェントが何をしたかです。ライブ観察で分かるのは、人間の誘導に対してエージェントがどう動くかです。Potatoのライブコーディングエージェントモードでは、アノテーターがコーディングエージェントの作業をリアルタイムで観察し（ファイルの読み取り、コードの編集、テストの実行）、任意のタイミングで介入できます。エージェントを一時停止する、新しい指示を送る、以前のチェックポイントにロールバックする、あるいはトラジェクトリを分岐させて別のアプローチを試す、といった操作が可能です。

これにより、静的なトレースだけの場合よりも情報量の多いアノテーションデータが得られます。タイムスタンプ付きの完全なトラジェクトリ、アノテーターの介入、分岐した判断点、そして別経路との比較データです。これらはプロセス報酬モデル、選好モデル、指示追従の評価器を訓練するのにそのまま使えます。

要件

Python 3.10以上
Git（チェックポイントシステムがgitコミットを使用します）
以下のエージェントバックエンドのいずれか
- ローカルでのモデル推論用のOllama（APIキー不要）
- Anthropic APIにアクセスするためのANTHROPIC_API_KEY
- Claude Codeのエージェント体験をそのまま使うClaude Agent SDK

バックエンド

Potatoはコーディングエージェントを実行するための3つのバックエンドに対応しています。いずれのバックエンドもエージェントをサブプロセスとして実行し、そのアクションをリアルタイムでアノテーションインターフェースにストリーミングします。

1. Ollama（ローカルモデル）

APIキーなしでローカルにコーディングエージェントを実行します。Ollamaはオープンウェイトモデルの高速な推論を提供します。開発やテスト、データをローカルマシンの外に出せない状況に適しています。

セットアップ：

bash

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
 
# Pull a coding-capable model
ollama pull qwen2.5-coder:7b
 
# Or a larger model for better performance
ollama pull deepseek-coder-v2:16b

設定：

yaml

agentic:
  enabled: true
  display_type: coding_trace
  live_agent:
    enabled: true
    backend: ollama
    model: qwen2.5-coder:7b
 
    ollama:
      host: "http://localhost:11434"    # Ollama server URL
      temperature: 0.2
      num_ctx: 8192                     # context window size
      num_predict: 2048                 # max tokens per response
      keep_alive: "5m"                  # keep model loaded in memory
 
    # Agent capabilities
    tools:
      - read_file
      - edit_file
      - write_file
      - bash
      - glob
      - grep
    max_steps: 50
    step_timeout_seconds: 60

2. Anthropic API

Anthropic API経由でClaudeモデルを使用します。ツール使用を伴うコーディング性能が高い一方、APIキーが必要です。

セットアップ：

bash

# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."
 
# Or add to .env file
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env

設定：

yaml

agentic:
  enabled: true
  display_type: coding_trace
  live_agent:
    enabled: true
    backend: anthropic
    model: claude-sonnet-4-20250514
 
    anthropic:
      api_key: ${ANTHROPIC_API_KEY}
      max_tokens: 4096
      temperature: 0.2
      system_prompt: |
        You are a coding assistant working on a software project.
        Read files before editing them. Run tests after making changes.
        Explain your reasoning before each action.
 
    # Agent capabilities
    tools:
      - read_file
      - edit_file
      - write_file
      - bash
      - glob
      - grep
    max_steps: 100
    step_timeout_seconds: 120

3. Claude Agent SDK

Claude Agent SDKは、ツールの自動オーケストレーション、コンテキスト管理、複数ファイルにまたがる推論を含む、Claude Codeのエージェント体験をそのまま提供します。最も高機能なバックエンドですが、SDKのインストールが必要です。

セットアップ：

bash

# Install the Claude Agent SDK
pip install claude-agent-sdk
 
# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."

設定：

yaml

agentic:
  enabled: true
  display_type: coding_trace
  live_agent:
    enabled: true
    backend: claude_agent_sdk
 
    claude_agent_sdk:
      api_key: ${ANTHROPIC_API_KEY}
      model: claude-sonnet-4-20250514
      max_turns: 100
      permission_mode: auto           # auto-approve tool use
      enable_thinking: true           # show extended thinking
 
    max_steps: 100
    step_timeout_seconds: 180

コントロール

アノテーションインターフェースには、エージェントの挙動を誘導するための4種類のコントロール操作があります。

一時停止／再開

Pauseをクリックすると、ステップの切れ目でエージェントが停止します。エージェントは現在のステップを終えてから待機します。アノテーターは現在の状態を確認し、ファイルを調べたうえで、そのまま続行させるか介入するかを判断できます。Resumeをクリックすると処理が再開します。

yaml

live_agent:
  controls:
    pause_resume:
      enabled: true
      auto_pause_on_error: true      # pause when a command fails
      auto_pause_after_steps: 0      # pause after N steps (0 = disabled)
      keyboard_shortcut: "Space"

指示の送信

エージェントが一時停止している間、アノテーターは新しい指示を送って進路を変えられます。エージェントが誤った方向に進んでいるときや、誘導に対する反応を試したいときに役立ちます。

yaml

live_agent:
  controls:
    send_instructions:
      enabled: true
      placeholder: "Type instructions for the agent..."
      inject_as: system_message      # "system_message" or "user_message"
      keyboard_shortcut: "Enter"
      presets:
        - "Try a different approach"
        - "Read the error message more carefully"
        - "Check the test file for expected behavior"
        - "Revert your last change and try again"

指示はエージェントの会話コンテキストに挿入されます。inject_asは、それをシステムメッセージ（強制力のある指示）として渡すか、ユーザーメッセージ（会話的な誘導）として渡すかを切り替えます。

ロールバック

ロールバックはプロジェクトを以前のgitチェックポイントの状態に戻します。エージェントによるファイル変更はすべて自動的にコミットされるため、アノテーターはタイムライン上の任意の過去ステップをクリックして、その時点の状態に正確に戻せます。エージェントの会話コンテキストもそれに合わせて切り詰められます。

yaml

live_agent:
  controls:
    rollback:
      enabled: true
      show_checkpoint_diff: true     # show what will be undone
      require_confirmation: true     # "Are you sure?" dialog
      keyboard_shortcut: "Ctrl+Z"

分岐と再生

分岐と再生は、ロールバックと指示送信を組み合わせたものです。アノテーターがチェックポイントまで戻り、別の指示を送ることで、トラジェクトリが分岐します。選好データを集めるときに有用で、同じ出発点から2つのアプローチを試して結果を比較できます。

yaml

live_agent:
  controls:
    branch:
      enabled: true
      max_branches: 5                # maximum branches from any checkpoint
      branch_naming: auto            # "auto" or "manual"
      compare_view: true             # side-by-side branch comparison
      keyboard_shortcut: "Ctrl+B"

分岐の比較ビューは2つの分岐を左右に並べ、どこで分かれたかを強調表示します。アノテーターはどちらの分岐がより良い結果を出したかを評価でき、DPO訓練用の選好ペアが生成されます。

Gitチェックポイントシステム

ライブエージェントモードは、すべてのファイル変更の追跡にgitを使用します。これにより、確実なロールバックと分岐、そして完全な変更履歴が得られます。

仕組み

エージェントの開始前に、Potatoがpotato-session-{session_id}という名前の新しいgitブランチを作成します
ファイル変更（編集、書き込み、作成、削除）のたびに、Potatoが説明的なメッセージを付けて自動コミットします
各コミットはチェックポイントとしてタグ付けされ、タイムラインに表示されます
ロールバックはgit checkoutを使い、作業ディレクトリを任意のチェックポイントの状態に復元します
分岐は、チェックポイントのコミットから新しいgitブランチを作成します

設定

yaml

live_agent:
  git_checkpoints:
    enabled: true
    branch_prefix: "potato-session"
    commit_message_format: "Step {step}: {tool} {file_path}"
    auto_commit: true
    cleanup_on_complete: false       # delete session branches when done
    require_clean_working_dir: true  # fail if there are uncommitted changes

チェックポイントの手動管理

bash

# List all Potato session branches
git branch | grep potato-session
 
# View checkpoints for a session
git log potato-session-abc123 --oneline
 
# Clean up old session branches
python -m potato.cleanup_sessions --older-than 7d

データ形式

ライブコーディングエージェントタスクの入力データには、タスクの説明と、必要に応じて開始時のファイルまたはディレクトリを指定します。

json

{
  "id": "task_001",
  "task_description": "Fix the bug in src/parser.py where empty input causes a crash",
  "project_dir": "/path/to/project",
  "start_file": "src/parser.py",
  "test_command": "python -m pytest tests/test_parser.py -v",
  "context_files": [
    "src/parser.py",
    "tests/test_parser.py"
  ]
}

フィールド	必須	説明
`id`	はい	タスクの一意な識別子
`task_description`	はい	エージェントに何をさせるか
`project_dir`	はい	プロジェクトディレクトリのパス
`start_file`	いいえ	最初にエージェントへ提示するファイル
`test_command`	いいえ	修正を検証するコマンド
`context_files`	いいえ	エージェントのコンテキストに事前読み込みするファイル

設定リファレンス

ライブコーディングエージェント観察タスクの完全な設定です。

yaml

task_name: "Live Coding Agent Observation"
task_dir: "."
 
data_files:
  - "data/coding_tasks.jsonl"
 
item_properties:
  id_key: id
  text_key: task_description
 
agentic:
  enabled: true
  display_type: coding_trace
 
  coding_trace_display:
    diff_style: unified
    diff_context_lines: 3
    syntax_highlight: true
    show_line_numbers: true
    terminal_theme: dark
    file_tree:
      enabled: true
      position: left
      click_to_navigate: true
 
  live_agent:
    enabled: true
    backend: anthropic
    model: claude-sonnet-4-20250514
 
    anthropic:
      api_key: ${ANTHROPIC_API_KEY}
      max_tokens: 4096
      temperature: 0.2
 
    tools:
      - read_file
      - edit_file
      - write_file
      - bash
      - glob
      - grep
 
    max_steps: 100
    step_timeout_seconds: 120
 
    controls:
      pause_resume:
        enabled: true
        auto_pause_on_error: true
        keyboard_shortcut: "Space"
      send_instructions:
        enabled: true
        inject_as: system_message
        presets:
          - "Try a different approach"
          - "Read the error message carefully"
          - "Run the tests first"
      rollback:
        enabled: true
        require_confirmation: true
      branch:
        enabled: true
        max_branches: 5
        compare_view: true
 
    git_checkpoints:
      enabled: true
      branch_prefix: "potato-session"
      auto_commit: true
      cleanup_on_complete: false
 
annotation_schemes:
  # Per-step ratings during observation
  - annotation_type: per_turn_rating
    name: step_quality
    description: "Rate each agent step as you observe it"
    target: agentic_steps
    rating_type: radio
    labels:
      - "Good"
      - "Acceptable"
      - "Unnecessary"
      - "Incorrect"
 
  # Overall task completion after agent finishes
  - annotation_type: radio
    name: task_completion
    description: "Did the agent complete the task?"
    labels:
      - "Fully Complete"
      - "Partially Complete"
      - "Failed"
 
  # Branch comparison (when branching is used)
  - annotation_type: radio
    name: branch_preference
    description: "Which branch produced a better result?"
    labels:
      - "Branch A"
      - "Branch B"
      - "Both Equal"
      - "Both Failed"
 
  # Notes on the observation
  - annotation_type: text
    name: observation_notes
    description: "Describe what you observed and any interventions you made"
    label_requirement:
      required: false
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

分岐トラジェクトリのエクスポート

アノテーターが分岐と再生を使うと、出力には分岐ツリー全体が含まれます。この形式は、比較トラジェクトリから選好モデルやプロセス報酬モデルを訓練することを想定しています。

json

{
  "id": "task_001",
  "annotator": "observer_01",
  "root_branch": {
    "branch_id": "main",
    "steps": [
      {"step": 0, "type": "file_read", "file": "src/parser.py", "rating": "Good"},
      {"step": 1, "type": "edit", "file": "src/parser.py", "rating": "Incorrect"}
    ],
    "children": [
      {
        "branch_id": "branch_1",
        "branch_point": 1,
        "instruction": "Try a different approach -- use a try/except block instead",
        "steps": [
          {"step": 2, "type": "edit", "file": "src/parser.py", "rating": "Good"},
          {"step": 3, "type": "terminal", "command": "pytest", "rating": "Good"}
        ],
        "outcome": "Fully Complete",
        "children": []
      },
      {
        "branch_id": "branch_2",
        "branch_point": 1,
        "instruction": "Read the test file first to understand expected behavior",
        "steps": [
          {"step": 2, "type": "file_read", "file": "tests/test_parser.py", "rating": "Good"},
          {"step": 3, "type": "edit", "file": "src/parser.py", "rating": "Good"},
          {"step": 4, "type": "terminal", "command": "pytest", "rating": "Good"}
        ],
        "outcome": "Fully Complete",
        "children": []
      }
    ]
  },
  "branch_preference": "Branch B",
  "observation_notes": "Both branches solved the problem, but branch B produced cleaner code by reading the tests first."
}

選好学習用に分岐トラジェクトリをエクスポートします。

bash

# Export as DPO preference pairs from branch comparisons
python -m potato.export \
  -i output/ \
  -f branching_dpo \
  -o results/branch_preferences.jsonl
 
# Export full trajectory trees
python -m potato.export \
  -i output/ \
  -f trajectory_tree \
  -o results/trajectory_trees.jsonl

セキュリティ

ライブエージェントは、タスクデータで指定されたプロジェクトディレクトリ内で動作します。そのディレクトリ内でファイルの読み取り、書き込み、実行が可能です。以下のセキュリティ上の運用を検討してください。

サンドボックス化：信頼できないコードや信頼できないエージェントモデルを扱う場合は、PotatoをDockerコンテナまたはVM内で実行してください。エージェントは任意のシェルコマンドを実行できるため、隔離が重要です。
読み取り専用モード：コードを変更させずに解析だけさせたい場合は、bashとwrite_fileのツールを無効にしてください。
ネットワーク制限：Dockerの--network noneフラグを使うと、エージェントがネットワークリクエストを行えなくなります。
リソース制限：max_stepsとstep_timeout_secondsを設定して、暴走を防いでください。

yaml

# Restricted tool set for analysis-only tasks
live_agent:
  tools:
    - read_file
    - glob
    - grep
  # No edit_file, write_file, or bash

トラブルシューティング

Ollamaが起動していない

text

Error: Connection refused at http://localhost:11434

Ollamaサーバーを起動します。

bash

ollama serve

起動を確認します。

bash

ollama list

APIキーが未設定

text

Error: ANTHROPIC_API_KEY environment variable not set

環境変数を設定します。

bash

export ANTHROPIC_API_KEY="sk-ant-..."

またはプロジェクトの.envファイルに追加してください。Potatoは.envファイルを自動的に読み込みます。

Gitが初期化されていない

text

Error: Project directory is not a git repository

チェックポイントシステムにはgitが必要です。プロジェクトディレクトリでリポジトリを初期化してください。

bash

cd /path/to/project
git init
git add -A
git commit -m "Initial commit"

エージェントがループに陥る

エージェントが同じアクションを何度も繰り返す場合、ループに陥っている可能性があります。Potatoは同じ引数での同じツール呼び出しが3回繰り返されるとループと判定し、自動的にエージェントを一時停止します。この閾値は設定できます。

yaml

live_agent:
  loop_detection:
    enabled: true
    threshold: 3                     # pause after N identical consecutive steps
    action: pause                    # "pause" or "terminate"

セッションブランチの後始末

時間が経つとセッションブランチが溜まっていきます。定期的に整理してください。

bash

# Remove branches older than 7 days
python -m potato.cleanup_sessions --older-than 7d
 
# Remove all session branches
python -m potato.cleanup_sessions --all
 
# Dry run (show what would be deleted)
python -m potato.cleanup_sessions --older-than 7d --dry-run

参考資料

コーディングエージェントアノテーション -- 静的なコーディングエージェントトレースのアノテーション
プロセス報酬アノテーション -- PRM訓練用のステップごとの報酬シグナルの収集
コードレビューアノテーション -- コード変更に対するGitHub PRスタイルのインラインレビュー
エージェント型アノテーション -- 汎用のエージェントトレースアノテーション

実装の詳細については、ソースドキュメントを参照してください。