Skip to main content

Module schema_normalization

adk_managed

Module schema_normalization 

Source
Expand description

Schema normalization for cross-provider MCP tool compatibility.

This module documents and tests the normalization contract that ensures MCP tool schemas are callable by all supported providers (Gemini, OpenAI, Anthropic, Ollama, OpenAI-compatible).

§How It Works

The managed runtime delegates schema normalization to each provider’s SchemaAdapter implementation in adk-model:

  • Gemini: Uses GenericSchemaAdapter — strips $schema, handles additionalProperties per Gemini’s requirements.
  • OpenAI: Uses OpenAiSchemaAdapter — strips $schema, conditional keywords, converts const to enum, adds implicit type: "object".
  • Anthropic: Uses AnthropicSchemaAdapter — strips $schema, handles Anthropic-specific schema restrictions.
  • Ollama: Uses GenericSchemaAdapter — minimal normalization.
  • OpenAI-compatible: Uses OpenAiSchemaAdapter — same as OpenAI.

§Provider Parity Contract

The key guarantee (Requirement 5.2):

Tool/response JSON-Schema normalization SHALL be applied per provider so MCP tools with $schema/additionalProperties/nested response schemas are accepted and callable by every provider.

This means: given the same MCP tool schema, after each provider’s SchemaAdapter::normalize_schema() is applied, the resulting schema is valid for that provider’s API. The tool is callable regardless of provider.

§Runtime Integration

When the ManagedAgentRuntime builds a runnable agent from a ManagedAgentDef:

  1. MCP server configs are used to connect to MCP servers.
  2. Tool schemas from MCP servers are collected.
  3. When the Runner invokes the LLM, the LLM’s schema_adapter() normalizes each tool schema before including it in the request.
  4. This happens transparently — the runtime does not need explicit normalization logic because adk-model providers handle it.

The tests in this module verify that the normalization contract holds for representative MCP tool schemas across all providers.

Functions§

normalize_for_provider
Verifies that a schema is normalized for a given provider adapter.
representative_mcp_schema
Returns a representative MCP tool schema that exercises common problem areas: