Repository navigation
Conversation
…ings ConversationSettings gains max_budget_per_run (USD, > 0, default None) in the general section next to max_iterations, and create_request() forwards it to StartConversationRequest.max_budget_per_run. Clients that render the conversation-settings schema (Agent Canvas) can now offer the budget, so conversations started from a UI are no longer unbounded by default. Co-authored-by: openhands <openhands@all-hands.dev>
REST API breakage checks (OpenAPI) — ✅ PASSEDResult: ✅ PASSED |
Coverage Report •
|
||||||||||||||||||||
all-hands-bot
left a comment
There was a problem hiding this comment.
This review was posted by an AI agent (OpenHands).
Scope gate
This change belongs here. The repository owns the Python SDK and Agent Server settings surface, and linked issue #5561 (ready-for-dev, priority:medium) explicitly assigns the SDK/agent-server side of per-conversation cost budgeting to this repo; the Canvas UI side is tracked separately in OpenHands/OpenHands#17691. No maintainer decision needed.
Technical assessment
The diff is small and additive: a persisted max_budget_per_run: float | None (gt=0, default None) on ConversationSettings, forwarded through _start_request_kwargs() via setdefault so explicit kwargs still override, plus tests.
Verified against the current head:
- Persistence/compatibility:
ConversationSettingsremains atCONVERSATION_SETTINGS_SCHEMA_VERSION = 1. The change is strictly additive with a nullable default, so a persisted v1 payload without the key validates toNone(no limit) — exactly the documented behavior. ThePersisted settingsCI gate and the repo'scheck_persisted_settings_compat.pyboth pass (33 fixtures, 8 PyPI baselines re-validated), including the v1conversation_settingsgolden fixture. No migration is required, and none is claimed. - Cross-layer trace: the field flows from settings →
create_request()→StartConversationRequest.max_budget_per_run→ the agent-server enforcement added in #6257 (request field, exclusion fromStoredConversation, budget check in the conversation loop, and update support inPATCHviamodel_fields_set). Theopenai/service.pygateway inherits it throughcreate_request()as described. The settings router round-tripsconversation_settings.model_dump(), so the new key survivesGET/PUT /api/settings— confirmed by the updated router test. Schema-driven clients pick the field up automatically viaexport_schema()(it sits in thegeneralsection next tomax_iterations, MAJOR prominence), and the generated TypeScript schema already carriesmax_budget_per_runon the conversation types from the earlier #6257 change. - Validation:
gt=0rejects 0 and negative budgets at model construction (covered by the parametrized test), so an unusable budget cannot be persisted or sent to the server. - Tests: the full focused suites pass in the workspace —
uv run pytest tests/sdk/test_settings.py tests/agent_server/test_settings_router.py -q→ 314 passed.
No material correctness, security, or compatibility defect in the code itself.
CI / acceptance
All checks on head aac2da64 pass except Validate PR description (fail): Add a short human-written note between HUMAN: and AGENT: — the HUMAN: section currently contains only HTML comments, and the validator requires ≥20 visible characters of human-written text. Per repository policy, AI agents must not edit the HUMAN: section; only the human author can fix it. This is a hard CI gate, so the PR cannot merge until the author adds the note. The failed check run is 43544053329; all other suites (including Persisted settings, REST API (OpenAPI), Check OpenAPI Schema, and the test matrix) are green.
The code is approvable as-is; the outstanding item is the human-authored note in the PR description.
🔄 CHANGES REQUESTED
The value is copied into each new conversation's start request; it does
not edit an existing conversation's budget (PATCH /api/conversations/{id}
does that). Rename the label to "Default budget per conversation (USD)"
and say so in the description.
Co-authored-by: openhands <openhands@all-hands.dev>
…udget Co-authored-by: openhands <openhands@all-hands.dev>
all-hands-bot
left a comment
There was a problem hiding this comment.
This review was posted by an AI agent (OpenHands).
Scope gate
Still belongs in this repository. The PR adds the settings-model half of per-conversation cost budgeting; linked issue #5561 (labels re-verified now: ready-for-dev, priority:medium, open) owns the SDK/agent-server side, and the Canvas UI side is tracked separately in OpenHands/OpenHands#17691. The prior review on aac2da64 passed the same gate.
What changed since the last review (aac2da6 → 7b5af73)
The head moved via two PR commits plus a merge from main (692604b8; every merged commit was verified to already exist on origin/main):
3fd41713relabels the field to Default budget per conversation (USD) and rewrites the description to state that the value applies to new conversations and that changing it does not affect existing ones (which usePATCH /api/conversations/{id}). This correctly documents the semantics against the server's existing create-time and PATCH-time budget handling (#6257), and the schema test now asserts the new label and the"new conversations"description text.7b5af738adds the exact case the previous review requested:ConversationSettings(max_budget_per_run=2.5).create_request(..., max_budget_per_run=5.0)now asserts5.0, pinning kwarg precedence over a different settings value. The review thread was answered and resolved.
Verification on the current head
- Focused suites pass in the workspace:
uv run pytest tests/sdk/test_settings.py tests/agent_server/test_settings_router.py -q→ 314 passed. - Persisted-settings compatibility gate passes:
uv run python .github/scripts/check_persisted_settings_compat.py→ 33 fixtures validated, 8 PyPI baselines (openhands-sdk==1.62.0) migrated and re-validated;ConversationSettingsstays at schema version 1, so a persisted v1 payload without the new key loads asNone(no limit) with no migration — as the PR claims. - The diff against current
origin/mainis unchanged in substance: the same additivemax_budget_per_runfield (gt=0, defaultNone) in thegeneralschema section plus the_start_request_kwargs()setdefaultforwarding. The settings router round-tripsconversation_settings.model_dump(), and the exported schema now carries the corrected label; the generated TypeScript client already mirrorsmax_budget_per_runfrom the earlier #6257 server work. No other supported entry point drops or ignores the field. - Newest
maincommits (through2aae48b6) touch none of this PR's files; no hidden conflicts with the settings surface. - The REST API contract diff embedded in the PR body (MCPOAuthStartRequest) originates from merged
maincommit2284096d(#6221), not from this PR's own change — consistent with theCheck OpenAPI Schemagate's diff-against-base reporting.
No material correctness, security, or compatibility defect on the current head.
CI / acceptance
All checks on 7b5af738 were still pending at review time except Validate PR description, which has already failed with the same error as before: Add a short human-written note between HUMAN: and AGENT: — the HUMAN: section still contains only HTML comments. Per repository policy AI agents must not edit the HUMAN: section, so only the human author can clear this hard merge gate. Everything the repository's acceptance review requires of the code itself is satisfied and green.
The code is ready; the outstanding item remains the human-authored note in the PR description.
🔄 CHANGES REQUESTED
HUMAN:
AGENT:
Why
The agent-server already enforces a per-conversation spend cap:
StartConversationRequest.max_budget_per_run(#6257) sets it at creation, andPATCH /api/conversations/{id}changes or removes it on an existing conversation. What is missing is a persisted default for new conversations.ConversationSettings, the settings model that clients render and thatcreate_request()turns into a start request, hasmax_iterationsand no budget. A self-hosted Agent Canvas user therefore cannot set a default cost limit: every conversation started from the UI is unbounded (only the 500-iteration cap applies). This is the SDK half of the cost-control request in #5561 / OpenHands/OpenHands#17691.Summary
ConversationSettings.max_budget_per_run: float | None(USD, must be > 0, defaultNone= no limit), labelled Default budget per conversation (USD). Its description says that the value applies to new conversations and that changing it does not affect existing ones (those usePATCH /api/conversations/{id}). It sits in thegeneralschema section next tomax_iterations, so schema-driven clients render it automatically.create_request()forwards it toStartConversationRequest.max_budget_per_runas a default; an explicit kwarg still overrides it. The OpenAI-compatible gateway (openai/service.py), which starts conversations throughcreate_request(), gets the budget the same way.create_requestforwarding and override (an explicit kwarg beats a different settings value, andNoneclears it), rejection of 0 and negative budgets; the settings-router expected body includes the new key.Issue Number
Part of #5561 (SDK side; the Canvas side is OpenHands/OpenHands#17691).
How to Test
Unit tests:
End to end with Agent Canvas (
npm run dev:minimalfrom the companion Canvas PR,OH_AGENT_SERVER_LOCAL_PATHpointing at this branch). The LLM is a local fake OpenAI-compatible server that returns token usage, so litellm prices each call at $0.03. The prompt makes the agent runsleep 125 times.GET /api/settings/conversation-schemareturnsgeneral: ['max_iterations', 'max_budget_per_run'](main: onlymax_iterations).0.2→ Save.GET /api/settings→conversation_settings.max_budget_per_run == 0.2.GET /api/conversations/<id>once a second:The run stops with Agent reached maximum budget limit ($0.2000); accumulated cost $0.2100 after 6 commands. On main the same prompt runs all 25 commands and costs $0.81, with
max_budget_per_run=null.Video/Screenshots
Design Doc
N/A (one settings field).
Type
Notes
None(no limit); no migration.This PR was created by an AI agent (OpenHands) on behalf of Graham Neubig.
🐳 Agent Server images for this PR — GHCR package, pull/run commands, and all pushed tags (click to expand)
• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server
Variants & Base Images
eclipse-temurin:17-jdkpython-node-runtimepython-node-runtimepython-node-runtimegolang:1.21-bookwormPull (multi-arch manifest)
# Each variant is a multi-arch manifest supporting both amd64 and arm64 docker pull ghcr.io/openhands/agent-server:7b5af73-pythonRun
All tags pushed for this build
About Multi-Architecture Support
7b5af73-python) is a multi-arch manifest supporting both amd64 and arm647b5af73-python-amd64) are also available if needed