feat(sdk/subagent): Support max_iteration_per_run in file-based agent definitions

[VascoSch92]

Summary

(ref #2186)

• Allow file-based agents (.md files) to specify max_iteration_per_run in their YAML frontmatter, controlling how many iterations a sub-agent can run before stopping
• The value must be strictly positive or omitted (defaults to None, which falls back to 500)
• Both DelegateExecutor and TaskManager now honor this setting when spawning sub-agent conversations

Example agent file:

  ---
  name: quick-checker
  description: A fast agent with limited iterations
  max_iteration_per_run: 10
  tools:
    - terminal
  ---
  System prompt here.

Checklist

• If the PR is changing/adding functionality, are there tests to reflect this?
• If there is an example, have you run the example to make sure that it works?
• If there are instructions on how to run the code, have you followed the instructions and made sure that it works?
• If the feature is significant enough to require documentation, is there a PR open on the OpenHands/docs repository with the same branch name?
• Is the github CI passing?

---

Agent Server images for this PR

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant	Architectures	Base Image	Docs / Tags
java	amd64, arm64	eclipse-temurin:17-jdk	Link
python	amd64, arm64	nikolaik/python-nodejs:python3.12-nodejs22	Link
golang	amd64, arm64	golang:1.21-bookworm	Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:64caffe-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-64caffe-python \
  ghcr.io/openhands/agent-server:64caffe-python

All tags pushed for this build

ghcr.io/openhands/agent-server:64caffe-golang-amd64
ghcr.io/openhands/agent-server:64caffe-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:64caffe-golang-arm64
ghcr.io/openhands/agent-server:64caffe-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:64caffe-java-amd64
ghcr.io/openhands/agent-server:64caffe-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:64caffe-java-arm64
ghcr.io/openhands/agent-server:64caffe-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:64caffe-python-amd64
ghcr.io/openhands/agent-server:64caffe-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-amd64
ghcr.io/openhands/agent-server:64caffe-python-arm64
ghcr.io/openhands/agent-server:64caffe-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-arm64
ghcr.io/openhands/agent-server:64caffe-golang
ghcr.io/openhands/agent-server:64caffe-java
ghcr.io/openhands/agent-server:64caffe-python

About Multi-Architecture Support

• Each variant tag (e.g., 64caffe-python) is a multi-arch manifest supporting both amd64 and arm64
• Docker automatically pulls the correct architecture for your platform
• Individual architecture tags (e.g., 64caffe-python-amd64) are also available if needed

[github-actions]

API breakage checks (Griffe)

Result: Failed

Log excerpt (first 1000 characters)

============================================================
Checking openhands-sdk (openhands.sdk)
============================================================
Comparing openhands-sdk 1.11.5 against 1.11.4
::notice title=openhands-sdk API::Ignoring Field metadata-only change (non-breaking): load_public_skills
::notice title=openhands-sdk API::Ignoring Field metadata-only change (non-breaking): temperature
::warning file=openhands-sdk/openhands/sdk/llm/llm.py,line=196,title=LLM.top_p::Attribute value was changed: `Field(default=1.0, ge=0, le=1)` -> `Field(default=None, ge=0, le=1, description='Nucleus sampling parameter. Defaults to None (uses provider default). Set to a value between 0 and 1 to control diversity of outputs.')`
::error title=SemVer::Breaking changes detected (1); require at least minor version bump from 1.11.x, but new is 1.11.5

============================================================
Checking openhands-workspace (openhands.workspace)
============================

Action log

[github-actions]

Agent server REST API breakage checks (OpenAPI)

Result: Passed

Action log

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk/subagent
registry.py	104	6	94%	77, 184–185, 189, 227–228
schema.py	66	3	95%	42, 55, 70
openhands-tools/openhands/tools/delegate
impl.py	129	110	14%	29, 31–32, 41–42, 46, 52–53, 56–59, 61, 73–74, 78–80, 84–85, 92–94, 103–104, 114–118, 120, 124, 128–129, 131–132, 137–139, 142, 148–149, 151, 153, 156, 161, 166, 170, 175–177, 194–195, 202–204, 213, 215–217, 220–225, 227, 234–235, 237–238, 241–244, 246–247, 251–254, 257–259, 264–265, 268–269, 274–278, 283, 285–289, 291, 294–296, 298–299, 302, 304, 309–311
openhands-tools/openhands/tools/task
manager.py	129	84	34%	64–66, 70–72, 79, 81, 84, 87–88, 92–93, 97, 101–104, 107–109, 111, 135–136, 138–139, 144, 150, 157–158, 163–165, 173, 180, 195, 197–198, 204–207, 209, 211, 219, 225, 235–236, 238–241, 243, 259–260, 264–265, 267–268, 271, 273, 277–278, 280–283, 285–293, 295–296, 298, 305–306, 312–313, 315
TOTAL	19650	6068	69%

[all-hands-bot]

🟢 Good taste - Clean, pragmatic implementation.

Solves a real problem (controlling sub-agent iteration limits) with the simplest possible approach: add a field, thread it through, use a clear priority system. Backward compatible, well-validated, properly tested.

The priority logic (factory > max_turns > 500 default) is straightforward and well-commented. No complexity, no special cases, no data structure issues. Exactly how features should be added.

LGTM! 👍

[enyst]

LGTM, thank you!