ToolSuture

APIs change. Your agent shouldn’t have to. ToolSuture restores broken tool compatibility around deployed agents—without rewriting them—and independently proves the original mission works again.

Comment

Inspiration

AI agents are becoming better at reasoning and acting, but many still depend on a fragile assumption: their tools will keep behaving the same way.

A provider can rename a field, reshape a response, change an enum, alter units, or even change what an operation means. When that happens, a deployed agent can lose a capability even though the agent itself is still correct.

That led to the question behind ToolSuture:

Can we restore compatibility around an already-deployed agent instead of rewriting the agent itself?

That became the core idea:

APIs change. Your agent shouldn't have to.

What it does

ToolSuture is an autonomous recovery layer for deployed agents whose external tool contracts have changed.

Its recovery loop is:

Observe → Diagnose → Policy → Plan → Validate → Repair → Replay → Verify → Record

ToolSuture compares the old contract, the new contract, the original task intent, provider semantics, and runtime evidence.

Gemini 3.6 Flash on Vertex AI handles the semantic question that a normal schema diff cannot:

Do the old and new contracts still mean the same thing for the agent's original mission?

If the migration is semantically equivalent, deterministic controls approve a bounded compatibility repair. ToolSuture applies that repair around the frozen agent, replays the original mission, and independently verifies the result.

In the primary demo, a shipment provider changes from a flat v1 response to a differently structured v2 contract. ToolSuture restores compatibility while the deployed Google ADK agent remains unchanged.

The result:

MISSION COMPLETED AND VERIFIED
CAPABILITY_LOST → CAPABILITY_RESTORED
0 BYTES CHANGED

ToolSuture also has a strict boundary.

In the dangerous scenario, a recoverable delete becomes irreversible permanent deletion. ToolSuture refuses before execution:

REFUSE
CRITICAL
BLOCKED
SAFE_HOLD
0 EXECUTION ATTEMPTS

The goal is not to repair everything.

The goal is to restore lost capabilities when meaning is preserved — and refuse when it is not.

How we built it

ToolSuture separates semantic reasoning, execution authority, and verification authority.

Gemini 3.6 Flash + Vertex AI

Gemini interprets the semantic migration using the old contract, new contract, original mission, provider semantics, and runtime evidence.

It produces structured diagnosis and repair-planning outputs, but it does not receive unrestricted authority to execute model-generated code or approve destructive behavior.

Google ADK

The demo agent is built with Google ADK and treated as already deployed.

Its source is intentionally frozen, and SHA-256 manifests verify that ToolSuture did not quietly solve the problem by editing the agent.

Deterministic policy and validation

Safe transformations are deliberately bounded, including:

  • response reshaping
  • grounded field mappings
  • grounded enum mappings
  • scoped unit conversions

Meaning-changing, permission-expanding, destructive, insufficiently grounded, or invalid migrations are blocked or refused.

Compatibility runtime

For approved migrations, ToolSuture creates a typed compatibility plan, applies deterministic transformations around the frozen agent, and replays the original mission through the changed MCP tool interface.

Independent verification

One design principle became central to the project:

The component that performs recovery does not get to certify that recovery succeeded.

ToolSuture never treats the agent's own success statement as proof. A separate verifier checks fresh, replay-linked provider evidence before the system can report CAPABILITY_RESTORED.

Google Cloud Run + Mission Control

ToolSuture is deployed publicly on Google Cloud Run, with Gemini running through Vertex AI.

Mission Control provides the live judge-facing interface and streams real recovery stages from the coordinator rather than simulated progress timers.

Challenges we ran into

The hardest challenge was not generating an adapter. It was deciding when an adapter should be allowed to exist at all.

At first, tool drift looked mostly structural: rename a field, reshape a response, convert a value.

But structural similarity can hide dangerous semantic changes.

A recoverable delete and an irreversible delete can look almost identical at the schema level while representing completely different actions.

That forced the architecture to separate:

semantic interpretation → deterministic authority → execution → independent verification

A second challenge was proving that recovery was real.

An agent saying "done" is not evidence that the external task actually succeeded. ToolSuture therefore links verification to the current replay and observed provider evidence.

A third challenge was failure handling. External model and provider calls can fail transiently, so ToolSuture had to fail closed: if replay or verification cannot establish the result, it withholds CAPABILITY_RESTORED instead of producing a false green state.

Accomplishments that we're proud of

The biggest accomplishment is that ToolSuture does not stop at diagnosing or proposing a repair — it actually restores the workflow and proves the original mission works again.

Current evidence includes:

  • 3 / 3 repeated verified Cloud recovery runs
  • 0 bytes changed to the frozen deployed agent
  • 16 / 16 independent checks on the primary safe recovery
  • provider evidence marked OBSERVED
  • replay provenance marked LINKED
  • 5 / 5 blind evaluation scenarios with the frozen recovery engine
  • dangerous semantic drift correctly classified REFUSE / BLOCKED
  • 0 execution attempts in the destructive case

I am also proud that the same product demonstrates both sides of autonomy:

safe migration → act

meaning-changing migration → refuse

Both are intentional system behavior.

What we learned

The biggest lesson was that AI reasoning is most useful when its authority is deliberately bounded.

Gemini is valuable for interpreting semantic relationships that would be difficult to encode as static rules. But interpretation, authorization, execution, and verification are different responsibilities.

Separating them made ToolSuture both more capable and easier to trust.

I also learned that production agent reliability is not only about making the agent smarter. Tool contracts, provider behavior, evidence, permissions, and failure modes all determine whether the mission still works after deployment.

That changed the question from:

"Can this agent complete the task?"

to:

"Can this capability survive change, and can the system prove that it still works?"

What's next for ToolSuture

The next step is expanding ToolSuture from a focused prototype into a broader compatibility layer for production agent ecosystems.

Future work includes:

  • broader MCP and API migration support
  • persistent migration history
  • stronger observability and rollback controls
  • configurable enterprise policy boundaries
  • proactive detection of contract drift
  • larger evaluations against real-world provider migrations

The long-term idea is simple:

Deployed agents should not become disposable every time the world around them changes.

ToolSuture is an experiment in giving those agents a safer way to keep working.

Built With

  • agentic-ai
  • ai-agents
  • api-compatibility
  • cloud-run
  • fastapi
  • gemini
  • google-adk
  • google-cloud
  • mcp
  • python
  • reliability
  • semantic-reasoning
  • verification
  • vertex-ai
  • workflow-automation
Share this project:

Updates

Submission history