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

requirements must identify one primary integration shape

Error message

requirements must identify one primary integration shape

What it means

Raised in select_protocol when the IntegrationRequirements flags match zero or multiple protocol shapes. Exactly one of dynamic_discovery (mcp), local_automation (cli), cross_agent_delegation (agent-to-agent), or direct_service_call (api) must be true; the chooser refuses ambiguous or empty requirements.

Solutions

1. Set exactly one primary requirement flag to True in the IntegrationRequirements dataclass
2. Split genuinely distinct integration needs into separate requirement objects
3. Remove contradictory flags (e.g. local_automation plus direct_service_call) from the scenario

When it happens

Trigger: Thrown at certifications/claude/lessons/25-integration-protocols-identity-and-least-privilege/code/main.py:35 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at certifications/claude/lessons/25-integration-protocols-identity-and-least-privilege/code/main.py:35

    local_automation: bool = False
    cross_agent_delegation: bool = False
    direct_service_call: bool = False
    long_running: bool = False


def select_protocol(requirements: IntegrationRequirements) -> str:
    selected = [
        name
        for condition, name in (
            (requirements.dynamic_discovery, "mcp"),
            (requirements.local_automation, "cli"),
            (requirements.cross_agent_delegation, "agent-to-agent"),
            (requirements.direct_service_call, "api"),
        )
        if condition
    ]
    if len(selected) != 1:
        raise ValueError("requirements must identify one primary integration shape")
    protocol = selected[0]
    if requirements.long_running and protocol == "cli":
        return "cli-with-durable-job"
    return protocol


@dataclass(frozen=True)
class Principal:
    principal_id: str
    scopes: frozenset[str]
    approved_actions: frozenset[str] = frozenset()


@dataclass(frozen=True)
class ToolContract:
    name: str
    description: str
    required_scopes: frozenset[str]

View on GitHub (pinned to 39ea8a1c6d)