देखें, रोकें और पीछे लौटें: Potato में लाइव कोडिंग एजेंट अवलोकन

लाइव अवलोकन अलग क्यों है

कोडिंग एजेंट का ज़्यादातर मूल्यांकन बाद में होता है: एजेंट चलता है, एक ट्रेस बनाता है, और समीक्षक उस रिकॉर्डिंग को बाद में खँगालते हैं। लाइव अवलोकन इसका उल्टा है। एनोटेटर एजेंट को असल समय में काम करते देखता है और हर फ़ाइल संपादन, टर्मिनल कमांड और तर्क-चरण को होते ही देख लेता है।

इससे आपके सामने नए विकल्प खुलते हैं। अगर एजेंट ग़लत रास्ते पर बढ़ने लगे, तो एनोटेटर वहाँ समय बर्बाद होने से पहले दख़ल दे सकता है। एजेंट के आगे बढ़ने से पहले वह रुककर diff ध्यान से पढ़ सकता है, या सादी भाषा में निर्देश भेजकर उसका रुख़ बदल सकता है। मुझे सबसे काम की चीज़ rollback लगती है: किसी भी पुराने चेकपॉइंट पर लौटकर आप एजेंट से दूसरा तरीक़ा आज़मा सकते हैं। ऐसी शाखाएँ ही वह डेटा हैं जिसकी प्रेफ़रेंस लर्निंग को ज़रूरत होती है।

यह स्थिर ट्रेस एनोटेशन की जगह लेने के लिए नहीं है। यह एक अलग तरीक़ा है जो अलग तरह का डेटा बनाता है। जब आपको अनुमानित लागत पर बहुत सारा डेटा चाहिए, तब स्थिर एनोटेशन बेहतर है। जब आपको लक्षित डेटा चाहिए, यह समझना हो कि एजेंट कैसे विफल होता है, या शाखाओं से प्रेफ़रेंस जोड़े बनाने हों, तब लाइव अवलोकन बेहतर है।

पूरे फ़ीचर संदर्भ के लिए स्रोत दस्तावेज़ देखें।

लाइव कोडिंग एजेंट इंटरफ़ेस एजेंट की क्रियाएँ असल समय में स्ट्रीम करता है और एजेंट के काम करते-करते कोड diff तथा टर्मिनल आउटपुट दिखाता है:

असल समय diff रेंडरिंग और टर्मिनल आउटपुट के साथ लाइव कोडिंग एजेंट अवलोकन

तीन बैकएंड

Potato लाइव अवलोकन के लिए तीन बैकएंड देता है। हर बैकएंड एक कोडिंग एजेंट को सैंडबॉक्स में चलाता है और उसकी क्रियाएँ होते ही इंटरफ़ेस तक स्ट्रीम करता है।

Ollama (पूरी तरह लोकल)

Ollama बैकएंड पूरी तरह आपकी मशीन पर चलता है, बिना किसी API कुंजी और बिना नेटवर्क कॉल के। जब कोडबेस संवेदनशील हो, या जब आप API का बिल बढ़ाए बिना बस प्रयोग करना चाहते हों, तब यही चुनें।

पहले Ollama इंस्टॉल करें और टूल इस्तेमाल की क्षमता वाला मॉडल खींचें:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh
 
# Pull a coding-capable model
ollama pull qwen2.5-coder:32b
 
# Verify the model is available
ollama list

Ollama बैकएंड इस्तेमाल करने के लिए Potato को कॉन्फ़िगर करें:

# config.yaml
project_name: "Live Agent Observation - Ollama"
port: 8000
 
live_coding_agent:
  enabled: true
  backend: "ollama"
  ollama:
    model: "qwen2.5-coder:32b"
    host: "http://localhost:11434"
    temperature: 0.2
    max_tokens: 4096
    num_ctx: 32768               # Context window size
  sandbox:
    type: "docker"               # "docker" or "local"
    image: "python:3.11-slim"    # Base image for sandboxed execution
    workspace: "./workspace/"    # Agent's working directory
    timeout: 600                 # Max seconds per agent session
  streaming:
    update_interval_ms: 100      # How often to push updates to the UI
    buffer_output: true          # Buffer terminal output for smoother rendering
  checkpoints:
    enabled: true
    strategy: "git"              # Git-based checkpoints
    auto_commit_on_file_change: true
    commit_message_prefix: "[potato-checkpoint]"

Anthropic API (टूल इस्तेमाल के साथ Claude)

Anthropic API बैकएंड टूल इस्तेमाल की क्षमता वाले Claude मॉडल से जुड़ता है। ज़्यादातर लोकल मॉडल के मुक़ाबले आपको बेहतर तर्क और कोड जनरेशन मिलता है, और बदले में API कॉल का ख़र्च देना पड़ता है।

# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."

# config.yaml
project_name: "Live Agent Observation - Claude"
port: 8000
 
live_coding_agent:
  enabled: true
  backend: "anthropic"
  anthropic:
    model: "claude-sonnet-4-20250514"
    api_key_env: "ANTHROPIC_API_KEY"
    max_tokens: 8192
    temperature: 0.1
    tools:
      - "file_read"
      - "file_edit"
      - "bash_command"
      - "directory_list"
      - "file_search"
    system_prompt: >
      You are a coding agent. You will be given a task description and
      access to a codebase. Use the provided tools to read files, make
      edits, and run commands to complete the task. Think step by step
      and verify your changes by running tests.
  sandbox:
    type: "docker"
    image: "python:3.11-slim"
    workspace: "./workspace/"
    timeout: 900
    allowed_commands:             # Whitelist for bash commands
      - "python"
      - "pip"
      - "pytest"
      - "git"
      - "ls"
      - "cat"
      - "find"
      - "grep"
  streaming:
    update_interval_ms: 50
    show_thinking: true           # Show Claude's thinking in real time
  checkpoints:
    enabled: true
    strategy: "git"
    auto_commit_on_file_change: true

Claude Agent SDK (पूरी Claude Code क्षमताएँ)

Claude Agent SDK बैकएंड तीनों में सबसे सक्षम है, जिसमें Claude Code के पूरे टूल सेट और स्वायत्त व्यवहार शामिल हैं। इसके लिए claude-agent-sdk पैकेज चाहिए।

# Install the Claude Agent SDK
pip install claude-agent-sdk

# config.yaml
project_name: "Live Agent Observation - Claude Agent SDK"
port: 8000
 
live_coding_agent:
  enabled: true
  backend: "claude_agent_sdk"
  claude_agent_sdk:
    api_key_env: "ANTHROPIC_API_KEY"
    model: "claude-sonnet-4-20250514"
    max_turns: 50                # Maximum number of agent turns
    permission_mode: "auto"      # "auto", "ask", or "restricted"
    allowed_tools:
      - "Read"
      - "Edit"
      - "Write"
      - "Bash"
      - "Glob"
      - "Grep"
    restricted_commands:          # Bash commands to block
      - "rm -rf /"
      - "sudo"
      - "curl"
      - "wget"
  sandbox:
    type: "docker"
    image: "node:20-slim"
    workspace: "./workspace/"
    timeout: 1200
    mount_volumes:
      - "./test-repo:/workspace/repo"
  streaming:
    update_interval_ms: 50
    show_thinking: true
    show_tool_inputs: true
  checkpoints:
    enabled: true
    strategy: "git"
    auto_commit_on_file_change: true
    max_checkpoints: 100

एनोटेशन कार्यप्रवाह

सर्वर चालू हो जाने के बाद लाइव अवलोकन सत्र कुछ चरणों से गुज़रता है।

सत्र शुरू करना

एनोटेटर Potato इंटरफ़ेस खोलता है और उसे टास्क विवरण का एक इनपुट फ़ील्ड दिखता है। वहाँ वह एजेंट के लिए टास्क लिखता या चिपकाता है, जैसे "नए config फ़ॉर्मैट की वजह से tests/test_parser.py में विफल हो रहा टेस्ट ठीक करें" या "/api/users एंडपॉइंट में pagination जोड़ें।"

# Start the server
potato start config.yaml -p 8000

एनोटेटर "Start Agent" पर क्लिक करता है और कोडिंग एजेंट काम शुरू कर देता है। हर क्रिया असल समय में CodingTraceDisplay पैनल में दिखती जाती है।

एजेंट को काम करते देखना

एजेंट के चलते-चलते हर चरण ट्रेस व्यूअर में दिखता है:

• तर्क-चरण समेटे जा सकने वाले धूसर ब्लॉक के रूप में दिखते हैं, जिनमें एजेंट का तर्क होता है।
• फ़ाइल पठन सिंटैक्स हाइलाइटिंग वाले कोड ब्लॉक के रूप में दिखते हैं, पंक्ति संख्याओं और फ़ाइल पथ के साथ।
• फ़ाइल संपादन लाल/हरे रंग की हाइलाइटिंग वाले unified diff के रूप में दिखते हैं।
• टर्मिनल कमांड गहरे रंग के टर्मिनल ब्लॉक के रूप में दिखते हैं, जिनमें कमांड, आउटपुट और exit code होते हैं।
• फ़ाइल ट्री साइडबार में तब-तब अपडेट होता है जब फ़ाइलें बनती, बदलती या पढ़ी जाती हैं।

ऊपर एक प्रगति संकेतक मौजूदा चरण संख्या और बीता समय दिखाता है। एजेंट की स्थिति "Thinking...", "Editing file...", "Running command..." वगैरह के रूप में दिखाई जाती है।

रोकने और निर्देश देने के नियंत्रण

एजेंट के चलते रहने के दौरान एनोटेटर कंट्रोल बार से दख़ल दे सकता है:

Pause: मौजूदा चरण पूरा होते ही एजेंट को रोक देता है। दोबारा शुरू किए बिना एजेंट अगले चरण पर नहीं जाता। एजेंट के आगे बढ़ने से पहले किसी diff या टर्मिनल आउटपुट को ध्यान से देखने के लिए इसका इस्तेमाल करें।

Send Instruction: रुके हुए (या चलते हुए भी) एजेंट के लिए सामान्य भाषा में संदेश लिखें, जो एजेंट के संदर्भ में डाल दिया जाता है। जैसे: "डेटाबेस स्कीमा मत बदलो, इसके बजाय migration इस्तेमाल करो" या "बदलाव करने से पहले /var/log/app.log में एरर लॉग देखो।"

Resume: रुकने के बाद एजेंट का चलना फिर से शुरू करता है।

Stop: एजेंट सत्र पूरी तरह ख़त्म कर देता है। यहाँ तक की ट्रैजेक्टरी सहेज ली जाती है।

एनोटेटर ट्रेस डिस्प्ले के साथ-साथ PRM एनोटेशन से एजेंट के काम का मूल्यांकन कर सकते हैं:

कोडिंग ट्रेस के साथ चरण-स्तरीय शुद्धता लेबलिंग के लिए PRM एनोटेशन इंटरफ़ेस

# Control bar configuration
live_coding_agent:
  controls:
    pause_enabled: true
    instruction_enabled: true
    stop_enabled: true
    rollback_enabled: true
    branch_enabled: true
    pause_keyboard_shortcut: "Space"
    instruction_keyboard_shortcut: "i"

git आधारित चेकपॉइंट सिस्टम

चेकपॉइंट सिस्टम ही वह चीज़ है जिससे बाक़ी सब चलता है। Rollback, branching और ट्रैजेक्टरी निर्यात, तीनों इसी पर टिके हैं, और यह अपना काम एजेंट के हर फ़ाइल बदलाव के बाद git में कमिट करके करता है।

यह कैसे काम करता है

सत्र शुरू होने पर Potato सैंडबॉक्स वर्कस्पेस में एक git रिपॉज़िटरी शुरू करता है, या पहले से मौजूद रिपॉज़िटरी इस्तेमाल करता है। हर फ़ाइल संपादन के बाद वह एक संरचित संदेश के साथ अपने आप कमिट कर देता है:

[potato-checkpoint] Step 7: Edit src/parser.py
- Modified lines 45-52
- Agent reasoning: Fix the regex pattern to handle escaped quotes

नतीजा एक रैखिक कमिट इतिहास होता है, जो ट्रैजेक्टरी के चरणों से एक-के-बदले-एक मेल खाता है। हर चेकपॉइंट उस समय वर्कस्पेस की पूरी स्थिति दर्ज कर लेता है।

# You can inspect checkpoints directly with git
cd workspace/
git log --oneline
 
# Output:
# f8a2c1d [potato-checkpoint] Step 12: Edit tests/test_parser.py
# 3b7e9f0 [potato-checkpoint] Step 10: Edit src/parser.py
# a1c4d8e [potato-checkpoint] Step 8: Edit src/parser.py
# 9e2f6b3 [potato-checkpoint] Step 5: Edit src/config.py
# 7d0a3c1 [potato-checkpoint] Step 0: Initial state

Rollback

"Rollback" पर क्लिक करें और ड्रॉपडाउन से कोई भी पुराना चेकपॉइंट चुनें। Potato git checkout से वर्कस्पेस को उस स्थिति में लौटा देता है और ट्रैजेक्टरी डिस्प्ले भी उसी हिसाब से पीछे कर देता है, फिर एजेंट वहीं से आगे बढ़ता है, संदर्भ उसी चरण तक छाँटा हुआ।

जब आप एजेंट को ग़लत मोड़ लेते देखें, तब यही करना चाहिए। उसे चलने देकर समय जलाने के बजाय आप आख़िरी सही स्थिति पर लौटते हैं और उसे दोबारा कोशिश करने देते हैं, शायद किसी निर्देश के साथ जो उसे बेहतर दिशा में धकेल दे।

शाखाओं वाली ट्रैजेक्टरी

Branching वह rollback है जो दोनों रास्ते बचाकर रखता है। जब आप पीछे लौटते हैं और एजेंट दूसरा रास्ता लेता है, तो Potato एक नामित git शाखा बनाकर दोनों ट्रैजेक्टरी पर नज़र रखता है:

Step 0 → Step 1 → Step 2 → Step 3 → Step 4 (Branch A: original path)
                          ↘
                           Step 3' → Step 4' → Step 5' (Branch B: after rollback)

आप किसी भी चेकपॉइंट से शाखा बना सकते हैं और ट्रैजेक्टरी का पूरा वृक्ष खड़ा कर सकते हैं। प्रेफ़रेंस लर्निंग के लिए यह सोना है, क्योंकि हर शाखा-जोड़ा पहले से ही लेबल की हुई तुलना है: आपने पीछे लौटने का फ़ैसला इसीलिए किया क्योंकि आपको Branch A ग़लत लगी, यानी शाखा-बिंदु से आगे Branch B ही पसंदीदा रास्ता है।

# Branching configuration
live_coding_agent:
  branching:
    enabled: true
    max_branches_per_session: 10
    auto_name_branches: true     # "branch-A", "branch-B", etc.
    require_reason_on_rollback: true  # Annotator must explain why they rolled back
    compare_branches_view: true  # Side-by-side view of branch outcomes

निर्यात फ़ॉर्मैट

एक लाइव सत्र से विस्तृत ट्रैजेक्टरी डेटा बनता है, और आप किस चीज़ के लिए प्रशिक्षण कर रहे हैं, उसके हिसाब से उसे कई रूपों में निर्यात कर सकते हैं।

रैखिक ट्रैजेक्टरी निर्यात

हर शाखा को एक स्वतंत्र ट्रैजेक्टरी के रूप में निर्यात करें:

potato export \
  --format trajectories \
  --project ./output/ \
  --output ./training_data/trajectories.jsonl \
  --flatten_branches true

{
  "session_id": "session_001",
  "branch": "branch-A",
  "task": "Fix the failing test in tests/test_parser.py",
  "steps": [
    {"step_idx": 0, "type": "file_read", "path": "tests/test_parser.py", "...": "..."},
    {"step_idx": 1, "type": "thinking", "content": "The test expects..."},
    {"step_idx": 2, "type": "file_edit", "path": "src/parser.py", "diff": "..."},
    {"step_idx": 3, "type": "bash_command", "command": "pytest tests/test_parser.py"}
  ],
  "human_interventions": [
    {"after_step": 2, "type": "instruction", "content": "Use a migration instead"}
  ],
  "rollback_from_step": null,
  "outcome": "resolved"
}

शाखाओं से प्रेफ़रेंस जोड़े

शाखा-जोड़ों को DPO या RLHF के लिए प्रेफ़रेंस डेटा के रूप में निर्यात करें:

potato export \
  --format branch_preferences \
  --project ./output/ \
  --output ./training_data/branch_preferences.jsonl

{
  "session_id": "session_001",
  "task": "Fix the failing test in tests/test_parser.py",
  "branch_point_step": 2,
  "branch_point_reason": "Agent started modifying the wrong file",
  "rejected_branch": "branch-A",
  "rejected_steps": [
    {"step_idx": 3, "type": "file_edit", "path": "src/wrong_file.py", "...": "..."},
    {"step_idx": 4, "type": "bash_command", "command": "pytest", "exit_code": 1}
  ],
  "chosen_branch": "branch-B",
  "chosen_steps": [
    {"step_idx": 3, "type": "file_edit", "path": "src/parser.py", "...": "..."},
    {"step_idx": 4, "type": "bash_command", "command": "pytest", "exit_code": 0}
  ]
}

लाइव अवलोकन से PRM लेबल

आप लाइव अवलोकन को PRM लेबलिंग के साथ जोड़ सकते हैं, क्योंकि rollback का बिंदु आम तौर पर पहली ग़लती वाला चरण होता है:

potato export \
  --format prm_from_branches \
  --project ./output/ \
  --output ./training_data/prm_live.jsonl

यहाँ जिस चरण से आपने rollback किया उसे पहली ग़लती का लेबल मिलता है, और नई शाखा के चरणों को सही का, क्योंकि आपने उन्हें स्वीकार किया था।

कोड रिव्यू डेटासेट

एनोटेटर के निर्देश और rollback के कारण कोड रिव्यू प्रशिक्षण डेटा के रूप में निर्यात करें:

potato export \
  --format code_review \
  --project ./output/ \
  --output ./training_data/code_review.jsonl

पूरा क्विक स्टार्ट

शून्य से लेकर चलते हुए Ollama सत्र तक का पूरा क्रम:

# 1. Install Potato with live agent support
pip install potato-annotation[live-agents]
 
# 2. Install and start Ollama
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull qwen2.5-coder:32b
 
# 3. Set up a workspace with a repo to work on
mkdir -p workspace/
git clone https://github.com/example/test-project workspace/repo
 
# 4. Create the config file
cat > config.yaml << 'YAML'
project_name: "Live Agent Observation"
port: 8000
 
live_coding_agent:
  enabled: true
  backend: "ollama"
  ollama:
    model: "qwen2.5-coder:32b"
    host: "http://localhost:11434"
    temperature: 0.2
    num_ctx: 32768
  sandbox:
    type: "local"
    workspace: "./workspace/repo"
    timeout: 600
  streaming:
    update_interval_ms: 100
  checkpoints:
    enabled: true
    strategy: "git"
    auto_commit_on_file_change: true
  controls:
    pause_enabled: true
    instruction_enabled: true
    rollback_enabled: true
    branch_enabled: true
  branching:
    enabled: true
    max_branches_per_session: 5
    require_reason_on_rollback: true
 
annotation_schemes:
  - annotation_type: radio
    name: outcome
    label: "Final outcome"
    options:
      - value: "resolved"
        text: "Task Fully Resolved"
      - value: "partial"
        text: "Partially Resolved"
      - value: "failed"
        text: "Failed"
 
  - annotation_type: text_input
    name: notes
    label: "Session Notes"
    placeholder: "Key observations about agent behavior..."
    required: false
 
output:
  path: "./output/"
  format: "jsonl"
  export_formats:
    - "trajectories"
    - "branch_preferences"
    - "prm_from_branches"
 
annotators:
  - username: "observer1"
    password: "observer_pw_1"
YAML
 
# 5. Start Potato
potato start config.yaml -p 8000
 
# 6. Open http://localhost:8000 in your browser

लॉग इन करने के बाद कोई टास्क चिपकाएँ, जैसे "/api/users POST एंडपॉइंट में इनपुट वैलिडेशन जोड़ें", और "Start Agent" पर क्लिक करें। उसे काम करते देखें, कुछ गड़बड़ लगे तो रोकें, दिशा बदलने के लिए निर्देश भेजें, और दूसरे तरीक़े आज़माने के लिए पीछे लौटें। काम पूरा होने पर नतीजे को रेट करें और नोट लिख दें।

बेहतर तरीक़े

साफ़, सीमित दायरे वाले टास्क से शुरू करें। सबसे उपयुक्त वे काम हैं जिनमें एजेंट को 5 से 15 मिनट लगें। इससे छोटे टास्क में इतनी ट्रैजेक्टरी बनती ही नहीं कि एनोटेट करने लायक हो; इससे कहीं लंबे टास्क एनोटेटर को थका देते हैं।

प्रोडक्शन में Docker सैंडबॉक्सिंग इस्तेमाल करें। विकास के दौरान लोकल सैंडबॉक्स मोड ठीक है, पर Docker एजेंट को आपके होस्ट सिस्टम तक पहुँचने नहीं देता। अविश्वसनीय मॉडल के साथ हमेशा इसी का इस्तेमाल करें।

rollback के कारण दर्ज करें। require_reason_on_rollback चालू रखें ताकि हर शाखा-बिंदु के साथ इंसान का लिखा एक नोट हो कि क्या ग़लत हुआ। वे नोट अपने आप में काम का प्रशिक्षण संकेत हैं, और प्रेफ़रेंस डेटा को भी बेहतर बनाते हैं।

कई बैकएंड की तुलना करें। एक ही टास्क Ollama, Anthropic API और Claude Agent SDK, तीनों से चलाकर एजेंटों के बीच प्रेफ़रेंस डेटा जुटाएँ। कॉन्फ़िग में सिर्फ़ बैकएंड वाला हिस्सा बदलना पड़ता है, इसलिए यह आसानी से हो जाता है।

जल्दी और बार-बार निर्यात करें। सब कुछ आख़िर के लिए बचाकर रखने के बजाय हर सत्र के बाद निर्यात चलाएँ। कुछ क्रैश हो जाए तो नुक़सान कम होता है, और आप साथ-साथ डेटा की गुणवत्ता पर भी नज़र रख पाते हैं।