AI Assistant 2.2.0 migration guide

This guide outlines the changes required to migrate AI Assistant from version 2.1.0 to 2.2.0.

Breaking change: user_id JWT claim required for rate limiting

Previously, the userId field in the client configuration (Web SDK or V2 API) was used as the identity for rate limiting. This meant a client could supply any userId on each request, making it possible to bypass rate limits.

Starting in 2.2.0, the user_id claim in the JSON Web Token (JWT) is the authoritative user identity for rate limiting. Rate limiting now requires the user_id claim to be set in the JWT.

Migration steps

1. If you use rate limiting (request_limit claim in the JWT) — Add a user_id claim to the JWT with the user’s identifier. Without it, the server will return a 401 error.
2. If you pass userId in the client configuration — If the JWT also includes a user_id claim, the two values must match. A mismatch will return a 401 error. Either remove userId from the client configuration, or ensure it matches the JWT user_id claim.
3. If you don’t use rate limiting or userId — No changes are required.

JWT before and after

Before:

{
  "document_ids": ["doc-1"],
  "request_limit": {
    "requests": 100,
    "time_period_s": 3600
  }
}

After:

{
  "document_ids": ["doc-1"],
  "user_id": "user-abc-123",
  "request_limit": {
    "requests": 100,
    "time_period_s": 3600
  }
}

Additional details

• The user_id claim must be a non-empty string.
• The user_id is stored as thread metadata for audit and ownership tracking.
• See the JWT claims guide for full details on all supported claims.

Deprecated: modelOverrides and model_overrides

AI Assistant 2.2.0 deprecates the modelOverrides request field and the agent_configuration.model_overrides JWT claim. Existing requests continue to work because the server translates them into the new modelServices.models shape, but new integrations should use modelServices and agent_configuration.model_services.

Migration steps

1. Replace JWT agent_configuration.model_overrides with agent_configuration.model_services.models.
2. Replace request modelOverrides with context.modelServices.models.
3. Don’t send both modelOverrides and modelServices in the same request. Doing so returns a 400 error.

JWT claim before and after

Before:

{
  "agent_configuration": {
    "model_overrides": {
      "default-llm": ["openai:*"]
    }
  }
}

After:

{
  "agent_configuration": {
    "model_services": {
      "models": {
        "default-llm": ["openai:*"]
      }
    }
  }
}

model_services.models supports the same model allowlist patterns as model_overrides: exact models, provider wildcards such as "openai:*", and the full wildcard "*".

Request body before and after

Before:

{
  "config": {
    "configurable": {
      "modelOverrides": {
        "default-llm": "openai:gpt-4o"
      }
    }
  }
}

After:

{
  "context": {
    "modelServices": {
      "models": [
        {
          "labels": ["default-llm"],
          "model": "openai:gpt-4o"
        }
      ]
    }
  }
}

MCP error handling change

Missing model context protocol (MCP) servers now surface as API errors instead of warnings. If you configure MCP servers, verify they’re reachable and correctly authenticated before upgrading.