EQTY LabDocs

Compatibility

What has to match for the SDK to work: the agent API and definition schema, the Viper release and its features, Python, and the model clients and frameworks it's tested with.

View as Markdown

The SDK talks to the local Viper proxy, writes definitions in a versioned schema, and reaches inside model clients and frameworks to route them. Each of those has to match.

The proxy

ga.Guardian checks the proxy before relying on it, the first time it’s used, and raises ga.ProxyIncompatible naming what’s missing. It sends nothing until the check passes (An incompatible proxy).

  • Agent API v1: the proxy’s local API (Proxy API).
  • Definition schema viper/agent-definition/v1: the schema the SDK writes. The proxy lists the schemas it accepts in capabilities().schemas.
  • Features: what the proxy does beyond the API version, by name. The SDK needs all five:
    • agent-headers: model requests name their agent, definition and sub-agent, and are signed as that agent;
    • error-marker: the proxy marks its own errors with X-Viper-Error;
    • collections: the proxy stores a skill’s or memory’s files;
    • thread-memory: a definition may record memory scoped to a thread;
    • model-betas: a definition may record the beta features a model’s requests carry.

The SDK goes by those features, never the proxy’s version number. Viper 0.3.0 is the first release with all five. Released Viper up to 0.2.1 lacks them and is refused, while a development build may report 0.2.1 and have them all, which is why the version number isn’t checked. To see what your proxy offers:

sh
curl "$VIPER_PROXY_URL/__viper__/v1/capabilities"

The definition schema

The definition is JSON, in the schema viper/agent-definition/v1, which the proxy and the Guardian Platform read. The SDK checks a definition against that schema, and the proxy’s own rules, before sending it (Definitions).

A definition’s content ID depends on its field names, which fields are optional, and when a field is left out. Those change only in a new schema version, so the same definition keeps its content ID across SDK and proxy releases. A framework release that changes what it builds, such as a reworded Deep Agents tool, changes what’s recorded, and so the content ID. Framework-specific data goes in extensions, so a framework can add to it without a new schema version.

Python

  • Python 3.10 or later, tested on 3.10 and 3.14.
  • Deep Agents needs Python 3.11 or later: the deepagents extra installs nothing on 3.10, and calling create_deep_agent there raises ModuleNotFoundError, saying so.

Model clients

bind() reaches inside the clients it routes, so they’re tested at their oldest supported release and newer ones:

  • OpenAI’s openai: 1.55.3 or later. CI tests 1.55.3 with httpx 0.28.1, the newest release built on httpx (2.x), and the release the SDK’s lockfile holds, built on httpx2.
  • Anthropic’s anthropic: 0.40.0 or later. CI tests 0.40.0, the newest built on httpx (0.x), and the release the SDK’s lockfile holds, built on httpx2.
  • httpx: 0.27 or later, below 1, for the SDK’s own calls to the proxy.

Older client releases fail with httpx 0.28 as soon as you create a client (Requirements).

Frameworks

The framework integrations depend on how each framework builds an agent, so LangChain, LangGraph, Deep Agents and the MCP packages are tested at their oldest supported release and the one the SDK’s lockfile holds; LangChain’s chat models at the locked release:

  • LangChain: langchain 1.2.11 or later, below 2, with langchain-core 1.6.10 or later, below 2. Older langchain releases can’t be installed with langgraph 1.1.10 or later. langchain-core 1.6.10 is the oldest release langchain-openai 1.7.2 and langchain-anthropic 1.7.7 install with, and CI runs them on it, with langchain 1.4.6; their newer releases need a newer langchain-core. CI tests langchain 1.2.11, langchain-core 1.6.10 and the locked releases.
  • LangGraph: langgraph 1.1.10 or later, below 2. CI tests 1.1.10 and the locked release.
  • Deep Agents: deepagents 0.7, tested at 0.7.0 and the locked 0.7 release. Deep Agents changes quickly before its 1.0, so only 0.7 is supported.
  • LangChain’s chat models: langchain-openai and langchain-anthropic 1.7. Another release may keep its client elsewhere, and bind() then refuses the model rather than guess.
  • MCP tools: langchain-mcp-adapters 0.3, with mcp 1.24 or later, below 2. CI tests 0.3.0 with mcp 1.24.0, and the locked releases.

The SDK’s own version

The SDK ships from EQTY Lab’s Cloudsmith repository (Package managers). Each release names the Viper release it needs.