docs: refresh AGENTS.md guidance

[all-hands-bot]

HUMAN:

---

AGENT:

Why

The subagent-specific AGENTS.md no longer matched the current implementation. It located built-in definitions in the SDK instead of openhands-tools, described built-ins as part of LocalConversation initialization, omitted supported frontmatter fields, and documented obsolete model and tool behavior.

Summary

• Correct built-in subagent ownership and first-registration-wins behavior.
• Document the current frontmatter schema, LLM profile loading, and tool/skill resolution.
• Update the minimal example to use current tool names and confirmation settings.

Issue Number

N/A — no related issue was identified.

How to Test

Validation performed from the repository root:

uv run pre-commit run --files openhands-sdk/openhands/sdk/subagent/AGENTS.md

All configured hooks reported Skipped because they target YAML or Python files, not Markdown.

A Python structural check also verified balanced fenced code blocks, valid local Markdown links, and the presence or removal of the corrected implementation claims. Finally, git diff --check passed and a scope check confirmed that only openhands-sdk/openhands/sdk/subagent/AGENTS.md changed.

No runtime tests were required because this pull request changes documentation only and does not alter executable behavior.

Video/Screenshots

N/A — documentation-only changes have no visual or runtime behavior to demonstrate.

Type

• Bug fix
• Feature
• Refactor
• Breaking change
• Docs / chore

Notes

This pull request was created by an AI agent (OpenHands) on behalf of the user.

---

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.13-nodejs22-slim	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:854d303-python

Run

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

All tags pushed for this build

ghcr.io/openhands/agent-server:854d303-golang-amd64
ghcr.io/openhands/agent-server:854d3031e9158d7eaadac8eae0f477b0e0588f8c-golang-amd64
ghcr.io/openhands/agent-server:openhands-refresh-agents-guidance-20260804-1717-golang-amd64
ghcr.io/openhands/agent-server:854d303-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:854d303-golang-arm64
ghcr.io/openhands/agent-server:854d3031e9158d7eaadac8eae0f477b0e0588f8c-golang-arm64
ghcr.io/openhands/agent-server:openhands-refresh-agents-guidance-20260804-1717-golang-arm64
ghcr.io/openhands/agent-server:854d303-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:854d303-java-amd64
ghcr.io/openhands/agent-server:854d3031e9158d7eaadac8eae0f477b0e0588f8c-java-amd64
ghcr.io/openhands/agent-server:openhands-refresh-agents-guidance-20260804-1717-java-amd64
ghcr.io/openhands/agent-server:854d303-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:854d303-java-arm64
ghcr.io/openhands/agent-server:854d3031e9158d7eaadac8eae0f477b0e0588f8c-java-arm64
ghcr.io/openhands/agent-server:openhands-refresh-agents-guidance-20260804-1717-java-arm64
ghcr.io/openhands/agent-server:854d303-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:854d303-python-amd64
ghcr.io/openhands/agent-server:854d3031e9158d7eaadac8eae0f477b0e0588f8c-python-amd64
ghcr.io/openhands/agent-server:openhands-refresh-agents-guidance-20260804-1717-python-amd64
ghcr.io/openhands/agent-server:854d303-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-amd64
ghcr.io/openhands/agent-server:854d303-python-arm64
ghcr.io/openhands/agent-server:854d3031e9158d7eaadac8eae0f477b0e0588f8c-python-arm64
ghcr.io/openhands/agent-server:openhands-refresh-agents-guidance-20260804-1717-python-arm64
ghcr.io/openhands/agent-server:854d303-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-arm64
ghcr.io/openhands/agent-server:854d303-golang
ghcr.io/openhands/agent-server:854d3031e9158d7eaadac8eae0f477b0e0588f8c-golang
ghcr.io/openhands/agent-server:openhands-refresh-agents-guidance-20260804-1717-golang
ghcr.io/openhands/agent-server:854d303-golang_tag_1.21-bookworm
ghcr.io/openhands/agent-server:854d303-java
ghcr.io/openhands/agent-server:854d3031e9158d7eaadac8eae0f477b0e0588f8c-java
ghcr.io/openhands/agent-server:openhands-refresh-agents-guidance-20260804-1717-java
ghcr.io/openhands/agent-server:854d303-eclipse-temurin_tag_17-jdk
ghcr.io/openhands/agent-server:854d303-python
ghcr.io/openhands/agent-server:854d3031e9158d7eaadac8eae0f477b0e0588f8c-python
ghcr.io/openhands/agent-server:openhands-refresh-agents-guidance-20260804-1717-python
ghcr.io/openhands/agent-server:854d303-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim

About Multi-Architecture Support

• Each variant tag (e.g., 854d303-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., 854d303-python-amd64) are also available if needed

[github-actions]

Python API breakage checks — ✅ PASSED

Result: ✅ PASSED

Action log

[github-actions]

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log