BerriAI/litellm · error · ValueError

Invalid model format. Expected format…

Error message

Invalid model format. Expected format: 'model=agent/AGENT_ID/ALIAS_ID'

What it means

The Bedrock InvokeAgent path requires exactly three '/'-separated model components with literal first part 'agent': agent/AGENT_ID/ALIAS_ID. _get_agent_id_and_alias_id raises this ValueError before any request is sent when the alias is missing, the prefix is absent or misspelled, or extra segments are present.

Solutions

  1. Use model="agent/<AGENT_ID>/<ALIAS_ID>" — take both ids from the agent's Aliases tab in the Bedrock console
  2. Remember the alias id is required: prepared-but-undeployed drafts answer to TSTALIASID, deployed aliases have their own id
  3. When configuring the LiteLLM proxy, encode the full three-part string in the deployment's model_name

Example fix

// before
resp = litellm.completion(model="agent/L1RT58GYRW", messages=msgs)

// after
resp = litellm.completion(model="agent/L1RT58GYRW/MFPSBCXYTW", messages=msgs)
Defensive patterns

Strategy: validation

Validate before calling

parts = model.split("/")
if len(parts) != 3 or parts[0] != "agent":
    raise ValueError(f"InvokeAgent model must be agent/AGENT_ID/ALIAS_ID, got {model!r}")
resp = litellm.completion(model=model, messages=msgs)

Type guard

def is_invoke_agent_model(model: str) -> bool:
    """True when model is a valid agent/AGENT_ID/ALIAS_ID triple."""
    parts = model.split("/")
    return len(parts) == 3 and parts[0] == "agent" and all(parts[1:])

Try / catch

try:
    resp = litellm.completion(model=model, messages=msgs)
except ValueError as e:
    if "Invalid model format" in str(e) and "AGENT_ID" in str(e):
        raise ConfigError(f"Use agent/<AGENT_ID>/<ALIAS_ID> (alias id required): {model!r}") from e
    raise

Prevention

When it happens

Trigger: model="agent/L1RT58GYRW" (agent id without alias id); model="L1RT58GYRW/MFPSBCXYTW" (no prefix); model="agents/..." typo; four segments from an appended path.

Common situations: Copying the agent id from the console but not the alias; using the human-readable agent name instead of the 10-character id; forgetting drafts are invoked via their test alias id (TSTALIASID); proxy config storing only part of the triple.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/63d3ed55bbabc40f. Report an issue: GitHub.

Appendix: source

Thrown at litellm/llms/bedrock/chat/invoke_agent/transformation.py:139

            optional_params=optional_params,
            request_data=request_data,
            api_base=api_base,
            model=model,
            stream=stream,
            fake_stream=fake_stream,
            api_key=api_key,
        )

    def _get_agent_id_and_alias_id(self, model: str) -> tuple[str, str]:
        """
        model = "agent/L1RT58GYRW/MFPSBCXYTW"
        agent_id = "L1RT58GYRW"
        agent_alias_id = "MFPSBCXYTW"
        """
        # Split the model string by '/' and extract components
        parts: Final = model.split("/")
        if len(parts) != 3 or parts[0] != "agent":
            raise ValueError("Invalid model format. Expected format: 'model=agent/AGENT_ID/ALIAS_ID'")

        return parts[1], parts[2]  # Return (agent_id, agent_alias_id)

    def _get_session_id(self, optional_params: dict) -> str:
        """ """
        return optional_params.get("sessionID", None) or str(uuid.uuid4())

    def transform_request(
        self,
        model: str,
        messages: list[AllMessageValues],
        optional_params: dict,
        litellm_params: dict,
        headers: dict,
    ) -> dict:
        # use the last message content as the query
        query: Final[str] = convert_content_list_to_str(messages[-1])
        return {

View on GitHub (pinned to 77b7c6c40c)