Skip to main content

aip_sdk.override_metric_config

aip_sdk.override_metric_config(config_name: str, metric_ref: MetricRef, *, workspace_id: str, params: dict[str, Any] | None = None, prompts: dict[str, PromptConfig] | None = None, client: APIClient | None = None) -> MetricConfig

Create the next config_version of config_name in workspace_id.

The assigned version is always server-derived — never accepted from the caller: the first override of a config name is "1.0.0", and every following one increments the leading segment of the highest existing numeric version. This is the only supported way to override a workspace config; unlike create_metric_config(), no caller guesses or computes config_version itself. The server retries internally when two concurrent overrides land on the same version, so most races resolve transparently; a MetricConfigOverrideConflictError only surfaces once that retry budget is exhausted (see Raises below).

Not idempotent, and the transport already retries for you. Each call inserts a new version, and the version is server-derived, so there is no key that makes a repeat safe: calling this twice with the same arguments creates two versions, not one. The underlying client itself retries a request up to twice more on a timeout or network error before this call raises — so by the time you see an exception here, the override may have already landed on one of those attempts. Read the config with get_metric_config() or list_metric_configs() before calling this again after any exception, rather than assuming nothing was written.

Parameters

  • config_name str: Configuration name to override the next version of.
  • metric_ref MetricRef: The metric implementation the new version parameterizes.
  • workspace_id str: The owning workspace.
  • params dict[str, Any] | None: Non-prompt parameters for the new version. Unlike MetricConfig.override(), there is no current payload here to carry over from — omitted (or None) means empty, not "keep the previous version's params."
  • prompts dict[str, PromptConfig] | None: Named Jinja2 prompt templates for the new version, keyed by slot name. Same replace-not-carry-over rule as params.
  • client APIClient | None: Optional pre-configured API client.

Returns

  • MetricConfig MetricConfig: the newly created version, with its server-assigned config_version.

Raises

  • MetricConfigOverrideConflictError: Concurrent overrides of this config name kept colliding (retry — check retryable, don't parse the message), or config_name is already bound to a different metric in this workspace (use a different name; not retryable).
  • MetricConfigValidationError: Existing versions of config_name exist but none parses as a numeric version to increment — a request-field fix will not help; the config name's version history needs to be numeric to have a next version.
  • NotFoundError: workspace_id names a workspace that does not exist.
  • ForbiddenError: The caller lacks a write-capable role in this workspace.
  • AuthError: If no credentials are configured.
  • APIError: If the request otherwise fails, or the response is malformed.

Example:

version = aip.override_metric_config(
    "rubric_prompt_a",
    aip.MetricRef(name="agent.custom_judge_rubric", implementation_version="1.0.0"),
    workspace_id="ws-abc123",
    params={"threshold": 0.9},
)
# version.config_version == "2.0.0", say — now pin it on a run.