Skip to content

Comments

Add OpenHands Cloud API automation scripts and workflow#103

Closed
enyst wants to merge 216 commits intomainfrom
test-cloud-api
Closed

Add OpenHands Cloud API automation scripts and workflow#103
enyst wants to merge 216 commits intomainfrom
test-cloud-api

Conversation

@enyst
Copy link
Owner

@enyst enyst commented Sep 24, 2025

This PR adds a minimal, useful toolkit to automate OpenHands Cloud via API and a GitHub Actions workflow to trigger new conversations.

What’s included

  • scripts/cloud_api.py: Typed API client (create/list/details/events/trajectory, LLM settings, polling, GitHub commenting)
  • scripts/llm_conversation.py: CLI to configure LLM settings and start conversations from templates or a custom prompt
  • scripts/prompts/: Reusable prompts plus common_tail.j2 conventions
  • create_conversation.py: Minimal helper to post a custom message + common tail
  • .github/workflows/new-conversation.yml: Manual workflow to start a conversation (optional polling) and comment a link to issue Conversations #95
  • scripts/README.md: Compact API usage notes and examples
  • scripts/test_api.py: Lightweight tests for client init, methods, and template rendering
  • agent_conversations.md: Tracker with an example active conversation

Secrets / env

  • OPENHANDS_API_KEY (required)
  • GITHUB_TOKEN (optional for commenting)
  • LLM_MODEL, LLM_BASE_URL, LLM_API_KEY (optional for configure-llm)

Quick usage

  • CLI example: python scripts/llm_conversation.py new-conversation --repository owner/repo --branch main --prompt-file new_conversation.j2 --poll
  • Combined: python scripts/llm_conversation.py configure-and-start --repository owner/repo --poll
  • Workflow: Dispatch “Start New OpenHands Conversation”, choose repo/branch and either a template or custom prompt

Notes

  • Events helper clamps limit to 1–100; list_conversations supports pagination
  • Small-window model detection helpers for recent/early events

Co-authored-by: openhands openhands@all-hands.dev

@enyst can click here to continue refining the PR

Summary by CodeRabbit

  • New Features

    • Added a GitHub Actions workflow to start OpenHands conversations with repository/branch inputs and optional polling.
    • Introduced a CLI to configure LLM settings and start conversations using templates or custom prompts, with optional GitHub commenting.
    • Added an API client for managing conversations, events, and settings.
  • Documentation

    • Added automation scripts README, conversation tracker, multiple prompt templates, and a TODO placeholder.
  • Tests

    • Added basic tests for API client initialization, method surface, and prompt template loading.

amanape and others added 30 commits August 20, 2025 15:33
Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: Engel Nyst <enyst@users.noreply.github.com>
…nds#10493)

Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: Engel Nyst <enyst@users.noreply.github.com>
Co-authored-by: openhands <openhands@all-hands.dev>
…8.18 (OpenHands#10561)

Co-authored-by: openhands <openhands@all-hands.dev>
…penHands#9707)

Co-authored-by: Engel Nyst <enyst@users.noreply.github.com>
…; apply across entrypoints; add tests (OpenHands#10540)

Co-authored-by: openhands <openhands@all-hands.dev>
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: Graham Neubig <neubig@gmail.com>
Co-authored-by: llamantino <213239228+llamantino@users.noreply.github.com>
Co-authored-by: mamoodi <mamoodiha@gmail.com>
Co-authored-by: Tim O'Farrell <tofarr@gmail.com>
Co-authored-by: Hiep Le <69354317+hieptl@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Ryan H. Tran <descience.thh10@gmail.com>
Co-authored-by: Neeraj Panwar <49247372+npneeraj@users.noreply.github.com>
Co-authored-by: sp.wack <83104063+amanape@users.noreply.github.com>
Co-authored-by: Insop <1240382+insop@users.noreply.github.com>
Co-authored-by: test <test@test.com>
Co-authored-by: Engel Nyst <enyst@users.noreply.github.com>
Co-authored-by: Zhonghao Jiang <zhonghao.J@outlook.com>
Co-authored-by: Ray Myers <ray.myers@gmail.com>
…gainst data exfiltration (OpenHands#10477)

Co-authored-by: Engel Nyst <enyst@users.noreply.github.com>
Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: Xingyao Wang <xingyao@all-hands.dev>
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: Xingyao Wang <xingyao@all-hands.dev>
Co-authored-by: Graham Neubig <neubig@gmail.com>
Co-authored-by: llamantino <213239228+llamantino@users.noreply.github.com>
Co-authored-by: mamoodi <mamoodiha@gmail.com>
Co-authored-by: Tim O'Farrell <tofarr@gmail.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Ryan H. Tran <descience.thh10@gmail.com>
Co-authored-by: Neeraj Panwar <49247372+npneeraj@users.noreply.github.com>
Co-authored-by: sp.wack <83104063+amanape@users.noreply.github.com>
Co-authored-by: Insop <1240382+insop@users.noreply.github.com>
Co-authored-by: test <test@test.com>
Co-authored-by: Engel Nyst <enyst@users.noreply.github.com>
Co-authored-by: Zhonghao Jiang <zhonghao.J@outlook.com>
Co-authored-by: Ray Myers <ray.myers@gmail.com>
…tests (OpenHands#10538)

Co-authored-by: openhands <openhands@all-hands.dev>
…nt (OpenHands#10579)

Co-authored-by: openhands <openhands@all-hands.dev>
…handler (OpenHands#10403)

Co-authored-by: openhands <openhands@all-hands.dev>
…0 in /frontend in the eslint group (OpenHands#10511)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
…management, memory UI) (OpenHands#10519)

Co-authored-by: amanape <83104063+amanape@users.noreply.github.com>
Co-authored-by: openhands <openhands@all-hands.dev>
…ands#10595)

Co-authored-by: amanape <83104063+amanape@users.noreply.github.com>
Co-authored-by: openhands <openhands@all-hands.dev>
…agent management) (OpenHands#10596)

Co-authored-by: amanape <83104063+amanape@users.noreply.github.com>
Co-authored-by: openhands <openhands@all-hands.dev>
Signed-off-by: hereisok <hereisok@angai.wk@gmail.com>
Co-authored-by: mamoodi <mamoodiha@gmail.com>
Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: OpenHands <openhands@all-hands.dev>
enyst and others added 28 commits September 24, 2025 00:41
Features added:
- Dropdown in GitHub Actions to select from available prompt files
- Text field for custom prompts that override prompt files
- New example prompt files: debug_issue.j2, code_review.j2, feature_implementation.j2
- Enhanced CLI with --prompt-file and --custom-prompt options
- Custom prompts take precedence over prompt files
- Improved user experience with clear feedback on prompt selection

The workflow now supports:
1. Selecting from predefined prompt templates via dropdown
2. Entering custom prompts directly in the workflow interface
3. Fallback to default new_conversation.j2 if no prompt specified

Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Major fixes:
- Remove hard-coded GitHub repo/issue targets (security risk)
- Add --comment-repo and --comment-issue CLI parameters for safe commenting
- Update function signature to accept comment parameters
- Remove GITHUB_TOKEN from workflow (no longer needed without hard-coded targets)
- Remove issues: write permission (no longer needed)
- Fix hard-coded conversation URL to use client.base_url
- Replace eval with safe array-based command building
- Add working-directory to workflow to avoid cd

All commenting is now opt-in and parameterized, eliminating security risks.
Tests still pass and functionality is preserved.
- Add back GITHUB_TOKEN and issues: write permission
- Automatically detect and comment on:
  - Current PR when triggered from pull_request event
  - Current issue when triggered from issues event
  - Issue 95 when triggered manually via workflow_dispatch
- Uses github.repository and github.event context for dynamic targeting
- Maintains security by using GitHub's built-in context instead of hard-coding

This restores the desired automatic posting behavior while being smarter
about which PR/issue to comment on based on the trigger context.
Issue 95 is the dedicated conversation log issue, so always post
success/error comments there regardless of trigger context.
This keeps all conversation results in one place for easy tracking.
…mon_tail.j2

Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: openhands <openhands@all-hands.dev>
- create_conversation.py: Enhanced conversation creation with multi-stage polling and LLM model detection
- agent_conversations.md: Tracking file for 17 active conversations with status and LLM models
- scripts/cloud_api.py: Enhanced API client with get_events method and condensation event examples
- scripts/prompts/common_tail.j2: Added shell safety warnings for agent runtime sessions
- todo_later.md: Future enhancement ideas including Stop prompt functionality

This framework enables automated management of multiple OpenHands Cloud conversations
with comprehensive tracking, LLM model detection, and event querying capabilities.
## Model Switching Discovery in Issue OpenHands#10730 Conversation

**UNPRECEDENTED FINDING**: OpenHands Cloud automatically switched LLM models mid-conversation during Issue OpenHands#10730 analysis.

### Key Discovery:
- **Conversation ID**: 5e1c2e15da9842d196ae29e44fc45f36
- **Total Events**: 297 events with 148 tool calls
- **Model Switch**: GPT-5 → Claude Sonnet 4 at event 252→262

### Model Usage Breakdown:
- **GPT-5 Phase**: 134 tool calls (events 9-252)
  - Primary work phase - analysis and implementation
  - Model: litellm_proxy/gpt-5-2025-08-07
- **Claude Sonnet 4 Phase**: 14 tool calls (events 262-296)
  - Final phase - completion and refinement
  - Model: litellm_proxy/claude-sonnet-4-20250514

### Significance:
- **First documented case** of automatic model switching in OpenHands Cloud
- **Clean handoff** with 9-event gap, no overlap
- **Task-appropriate routing**: GPT-5 for heavy analysis, Claude for completion
- **Platform intelligence**: Demonstrates sophisticated AI orchestration

### Additional Research Findings:
- **API vs UI Routing**: Different model selection algorithms
- **API Deterministic**: 100% consistent content-based routing
- **UI Probabilistic**: Variable routing with user behavior influence
- **GPT-5 Breakthrough**: First success via UI after 12 attempts

### Files Added:
- agent_conversations.md: Complete conversation fleet tracking (37 conversations)
- issue_10730_complete_trajectory_297_events.json: Full 297-event trajectory (1.8MB)

This discovery reveals OpenHands Cloud as a sophisticated AI orchestration platform with intelligent model routing capabilities.

Co-authored-by: openhands <openhands@all-hands.dev>
…-2025-08-07)\n\nCo-authored-by: openhands <openhands@all-hands.dev>
…b6a09ada34259 (prefix discrepancy)\n\nCo-authored-by: openhands <openhands@all-hands.dev>
…oints

- Add list_conversations and helpers in scripts/cloud_api.py
- Append missing conversations with minimal info only (no trajectories)

Co-authored-by: openhands <openhands@all-hands.dev>
…om list endpoint\n\n- get_early_model() using first 20 events only for unknowns\n- Add notes on events count and model probe strategy\n- Single-pass enrich MD with trigger and PR references\n\nCo-authored-by: openhands <openhands@all-hands.dev>
…probe (20 events)\n\nCo-authored-by: openhands <openhands@all-hands.dev>
- Add validation to clamp limit parameter between 1 and 100
- Prevents server-side errors from out-of-range limit values
- Addresses review comment on PR #94

Co-authored-by: openhands <openhands@all-hands.dev>
…ons.md\n\nWe do not commit trajectory files; remove stray references.\n\nCo-authored-by: openhands <openhands@all-hands.dev>
…ls via reverse-window probe\n\nCo-authored-by: openhands <openhands@all-hands.dev>
…cy (GPT-5 without litellm_proxy/)\n\nCo-authored-by: openhands <openhands@all-hands.dev>
…itching case confirmed\n\nCo-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
…l-Hands-AI/agent-sdk\n\n- Include link and initial status\n- Will populate model when detected\n\nCo-authored-by: openhands <openhands@all-hands.dev>
…d7ca4a98445d1b9e9d0fbe3fc2898\n\nCo-authored-by: openhands <openhands@all-hands.dev>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.