Skip to content

docs: refresh AGENTS.md guidance #424

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
all-hands-bot wants to merge 1 commit into
base: main
Choose a base branch
from
+10 −34
Open

docs: refresh AGENTS.md guidance #424

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 10 additions & 34 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,14 @@
# Automations Service

Self-contained microservice that schedules and dispatches automation runs inside OpenHands Cloud sandboxes.
Self-contained microservice that schedules and dispatches automation runs inside OpenHands sandboxes.

## Cross-Repository Boundaries

This repository owns the Automation Service: automation definitions, cron scheduling, webhooks, run history, dispatch, and sandbox lifecycle orchestration. It manages when work runs and dispatches conversations to the Agent Server/SDK, which owns agent/tool behavior, conversations, workspaces, events, and API endpoints.

Related repositories have different responsibilities:

- [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) owns the Python SDK, Agent Server, canonical API, and execution behavior.
- [`OpenHands/typescript-client`](https://github.com/OpenHands/typescript-client) owns the browser-compatible typed client for the Agent Server API.
- [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) owns the Python SDK, Agent Server, canonical API, execution behavior, and the browser-compatible TypeScript client under `clients/typescript/`.
- [`OpenHands/OpenHands`](https://github.com/OpenHands/OpenHands) owns Agent Canvas UI, frontend integration, and local-stack orchestration.
- [`OpenHands/extensions`](https://github.com/OpenHands/extensions) owns reusable skills, plugins, automations, and integrations.

Expand Down Expand Up @@ -63,8 +62,7 @@ automation/
│ └── test_tarball/ # Tarball contents uploaded to sandbox during test
│ ├── main.py # Test script run inside sandbox (SDK workspace test)
│ └── setup.sh # Installs SDK inside sandbox
├── tests/ # Unit tests (flat structure, no external deps)
│ ├── integration/ # Integration tests (require OPENHANDS_API_KEY)
├── tests/ # Unit and container-backed integration tests
│ ├── test_auth.py
│ ├── test_dispatcher.py
│ ├── test_execution.py
Expand All @@ -74,28 +72,12 @@ automation/
└── pyproject.toml
```

## Cross-Repo Coordination

Three repos work together:

| Repo | Branch | Purpose |
|------|--------|---------|
| `OpenHands/automation` | `dispatch-phase1b` | Automation service (this repo) |
| `OpenHands/deploy` (aka `All-Hands-AI/deploy`) | `dispatch-phase1b` | Deploys automation as a sidecar |
| `OpenHands/software-agent-sdk` | `feat/saas-runtime-mode` | SDK changes for in-sandbox execution |

**AUTOMATION_SHA linking**: The deploy repo references a specific automation commit in two workflow files:
- `.github/workflows/deploy.yaml` → `AUTOMATION_SHA: "<full-sha>"`
- `.github/workflows/deploy-automation.yaml` → `AUTOMATION_SHA: "<full-sha>"`

After pushing to the automation repo, update both files in the deploy repo.

## Configuration

Configuration is centralized in `config.py` using a composed `AppConfig` with typed sections:

```python
from automation.config import get_config
from openhands.automation.config import get_config

config = get_config()
config.service.db_host # ServiceSettings (AUTOMATION_ prefix)
Expand All @@ -117,15 +99,12 @@ config.log.log_level # LogSettings (no prefix)

```bash
# Pre-commit (run from repo root)
pre-commit run --files openhands/**/*.py scripts/**/*.py tests/**/*.py --show-diff-on-failure

# Unit tests (no external deps, skips Docker-dependent tests)
uv run pytest tests/ -v --ignore=tests/integration
uv run pre-commit run --all-files --show-diff-on-failure

# Integration test (requires OPENHANDS_API_KEY)
OPENHANDS_API_KEY=sk-oh-... uv run pytest tests/integration/ -v
# Test suite (requires Docker for the PostgreSQL fixture; some tests also use MinIO or fake-gcs-server containers)
uv run python -m pytest tests/

# E2E test script (live sandbox, ~80s)
# E2E test script (requires OPENHANDS_API_KEY and a live sandbox service)
OPENHANDS_API_KEY=sk-oh-... uv run python scripts/test_automation.py --api-url https://staging.all-hands.dev
```

Expand Down Expand Up @@ -276,8 +255,8 @@ The `/v1/preset/prompt` endpoint allows creating automations by simply providing
### Notes

- The `presets/` directory is excluded from ruff and pyright linting since it contains SDK code that runs in the sandbox, not application code
- The generated tarball uses `python main.py` as the entrypoint and `setup.sh` as the setup script
- Future presets (e.g., plugins) can be added as additional subdirectories under `openhands/automation/presets/`
- Generated presets use `.venv/bin/python main.py` on POSIX (`.venv/Scripts/python.exe main.py` on Windows) as the entrypoint and `setup.sh` as the setup script
- Prompt and plugin presets live in separate subdirectories under `openhands/automation/presets/`

## Catalog Bundles

Expand Down Expand Up @@ -490,6 +469,3 @@ When bumping `openhands-sdk` / `openhands-workspace` pins:
2. Run `uv lock` to regenerate `uv.lock`.
3. Open a Conventional Commit PR (e.g. `fix: bump SDK to <ver>`) and squash-merge it —
release-please handles the version bump and release.
4. After the release publishes, update `AUTOMATION_SHA` in the deploy repo:
- `.github/workflows/deploy.yaml`
- `.github/workflows/deploy-automation.yaml`
Loading