rohitg00/ai-engineering-from-scratch · warning · ValueError

managed requirements need explicit acceptance of the current

Error message

managed requirements need explicit acceptance of the current beta boundary

What it means

choose_runtime raises ValueError('managed requirements need explicit acceptance of the current beta boundary') when RuntimeNeeds requests a managed sandbox or remote durable session but accepts_managed_beta is False. The function refuses to silently route workloads onto a beta-stage managed-agents runtime; the caller must opt in knowingly.

Source

Thrown at certifications/claude/lessons/10-tool-use-and-agentic-loops/code/main.py:37

@dataclass(frozen=True)
class RuntimeNeeds:
    """Facts that decide how much agent-loop infrastructure to adopt."""

    open_ended: bool
    supported_sdk: bool = True
    needs_custom_wire_control: bool = False
    needs_managed_sandbox: bool = False
    needs_remote_durable_session: bool = False
    accepts_managed_beta: bool = False


def choose_runtime(needs: RuntimeNeeds) -> str:
    """Choose a workflow, hand-written loop, Tool Runner, or managed agent."""
    if not needs.open_ended:
        return "deterministic-workflow"
    if needs.needs_managed_sandbox or needs.needs_remote_durable_session:
        if not needs.accepts_managed_beta:
            raise ValueError("managed requirements need explicit acceptance of the current beta boundary")
        return "managed-agents"
    if needs.needs_custom_wire_control or not needs.supported_sdk:
        return "hand-written-loop"
    return "sdk-tool-runner"


@dataclass(frozen=True)
class CapabilityNeeds:
    """Separate executable capability from optional reusable procedure."""

    reusable_procedure: bool = False
    shared_standard_service: bool = False
    provider_executed_builtin: bool = False
    anthropic_schema_client_tool: bool = False


def choose_capability_surface(needs: CapabilityNeeds) -> dict[str, str]:
    execution_flags = sum(

View on GitHub (pinned to 39ea8a1c6d)

Solutions

1. Set accepts_managed_beta=True when the product decision to ride the beta managed-agents runtime has actually been made.
2. If beta risk is unacceptable, clear needs_managed_sandbox / needs_remote_durable_session so choose_runtime returns hand-written-loop or sdk-tool-runner instead.
3. Gate the managed-runtime option in UIs behind an explicit consent control that writes accepts_managed_beta.
4. Catch the ValueError in decision-lab callers and surface it as a decision-required prompt rather than a crash.

Example fix

# before
runtime = choose_runtime(RuntimeNeeds(open_ended=True, needs_managed_sandbox=True, accepts_managed_beta=False))
# ValueError: managed requirements need explicit acceptance...

# after
runtime = choose_runtime(RuntimeNeeds(open_ended=True, needs_managed_sandbox=True, accepts_managed_beta=True))  # -> "managed-agents"

def ready_for_managed(needs: RuntimeNeeds) -> bool:
    managed = needs.needs_managed_sandbox or needs.needs_remote_durable_session
    return not managed or needs.accepts_managed_beta

def is_runtime_choice_safe(needs: RuntimeNeeds) -> bool:
    """True when choose_runtime(needs) will not raise."""
    if not needs.open_ended:
        return True
    if needs.needs_managed_sandbox or needs.needs_remote_durable_session:
        return needs.accepts_managed_beta
    return True

try:
    runtime = choose_runtime(needs)
except ValueError:
    # beta consent missing: prompt instead of crashing
    if not ask_consent("managed runtime is in beta, proceed?"):
        needs.needs_managed_sandbox = needs.needs_remote_durable_session = False
    needs.accepts_managed_beta = True
    runtime = choose_runtime(needs)

When it happens

Trigger: choose_runtime(RuntimeNeeds(open_ended=True, needs_managed_sandbox=True, accepts_managed_beta=False)), or needs_remote_durable_session=True with accepts_managed_beta unset/False. Reached via decision_lab and tests test_managed_runtime_requires_explicit_beta_acceptance and test_runtime_choice_preserves_workflow_gate.

Common situations: Default-constructing RuntimeNeeds (accepts_managed_beta defaults False) while flipping sandbox/session flags; a decision-checklist tool where the user never ticked the beta-consent box; copying example needs objects from docs that predate the flag.

Related errors

• tool_use requires name and object input
• response content must be a non-empty block list
• every content block needs a type
• event arrived after message_stop
• stream ended without message_stop

AI-assisted analysis of rohitg00/ai-engineering-from-scratch@39ea8a1c6d (2026-08-26). Data as JSON: /api/errors/57265cfdc7461c4b. Report an issue: GitHub.