# Migrate Osworld Agent

> Migrate an agent from upstream OSWorld into this OSWorld-V2 repository, add matching evaluation entrypoints, and verify the integration.

- Skill: `amap-ml/migrate-osworld-agent` (Agent Skill)
- Install (CLI): `npx skillmds@latest add amap-ml/migrate-osworld-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/amap-ml/migrate-osworld-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: amap-ml (https://skillmd.com/u/amap-ml)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/amap-ml/migrate-osworld-agent

---


# Migrate OSWorld Agent

Use this when adding an upstream OSWorld agent to this repo.

## Workflow

1. Read the upstream agent.
2. Read local patterns before editing:
   - use `scripts/python/run_multienv_claude.py` as the main runner reference
   - use `scripts/bash/run_multienv_claude.sh` as the shell entrypoint reference
   - if a similar local agent exists, use it only for interface shape
   - if none exists, derive the interface from the runner and `DesktopEnv`
3. Copy the agent into `mm_agents/` with a clear, non-conflicting name.
4. Adapt only the repo-facing interfaces:
   - `predict()` return shape
   - action dict fields consumed by `DesktopEnv.step()`
   - `ASK_USER` turns and follow-up user responses
   - done/fail markers
   - task current date
   - platform, screen, provider, and password settings
5. Add a matching multi-env Python runner under `scripts/python/run_multienv_<agent>.py`.
   - start from the closest retained runner structure
   - keep task loading, env recreation, checkpoint args, logs, and cleanup behavior
   - remove provider/model checks that only apply to the source runner
6. Add a small shell entrypoint under `scripts/bash/`.
   - use `uv run`
7. Keep unrelated agents, scripts, results, and local dirty files out of the change.

## Verify

Run fast checks first.

- Compile the new Python files.
- Check shell syntax.
- Check staged diff for whitespace.
- Run local fake tests for:
  - action parsing
  - `ASK_USER`
  - user response returning to the agent
  - checkpoint argument parsing if touched

Then run one small real smoke test.

- Use the intended provider.
- Use a tiny step limit.
- Prefer public IP for cloud providers when the local machine cannot reach private IPs.
- Confirm the model call happens.
- Confirm at least one environment action executes.
- Confirm result files and trajectory are written.
- Confirm cloud resources are cleaned up.

Before opening a PR, stage only the migration files and re-run the fast checks.