Semantic Contract Verification for Agent Handoffs

You have defined the JSON schema for your agent handoffs. The types match. The fields are present. The tests pass. Yet, downstream logic still breaks. The receiving agent sees a valid string but interprets it as a different state than the sender intended. You wanted deterministic reliability. You got a steady stream of incidents where shared data means different things to different parts of the system.

The pain is not in the code. It is in the gap between structure and meaning. An agent sends status: "done". Another agent expects status: "completed". Both are valid strings. Neither is valid logic. You are debugging production behavior that should have been caught at the boundary.

How do I decide between static types and runtime assertions?

Pick runtime semantic assertions for any field where meaning changes based on context. Static types are necessary but insufficient. They verify shape, not intent. If a field can hold a value that is structurally correct but logically wrong for the current step, you need a runtime check.

Build the assertion layer first for critical handoffs. Defer it for low-risk informational fields. The proof you need is simple: can you catch a mismatch before the next agent acts on it? If yes, you unlock the ability to let agents operate with less human oversight. If no, you are just adding latency to a problem you cannot solve.

Start with the fields that have caused incidents. Do not try to verify everything at once. Focus on the high-entropy fields where interpretation is ambiguous. This keeps the initial build small and the signal clear.

What does silent semantic drift look like in production?

It looks like a valid payload that causes a logic error three steps later. The drift is silent because no exception is thrown. The data flows through the pipeline. The receiving agent processes it based on its own internal model. The result is wrong, but the error is not localized to the handoff.

Common patterns include field ambiguity, unit mismatch, and temporal drift. A status field might mean "completed" in Agent A and "pending review" in Agent B. A numeric field might lack unit context, causing a scale error. A timestamp might be interpreted in different timezones without explicit metadata.

Each of these is a structural pass and a semantic fail. The data looks fine. The logic breaks. You spend hours tracing the data back through the pipeline to find the point where the meaning shifted. That time is the cost of not verifying semantics at the boundary.

When should I enforce assertions versus just log them?

Enforce them when the cost of a bad handoff exceeds the cost of a halt. Log them when you are still mapping the drift patterns. Shadow mode is your friend here. Run assertions in parallel without blocking the pipeline.

This proves detection value. You see how often the semantic invariant fails. You see which fields are the most ambiguous. You build trust in the assertion logic without risking availability. Once the false positive rate is low, switch to enforcement.

The transition from logging to enforcement is a trust decision. You are betting that the assertion is correct. If it is wrong, you are introducing a new failure mode. Shadow mode lets you make that bet with data, not hope.

Why do standard schema validations fail to catch these errors?

Because they are shape-based, not state-based. A JSON schema knows that a field is a string. It does not know what that string means in the context of the workflow. It cannot know that "done" is not the right state for a step that requires "verified".

Schema validation is a static check. It happens once, at the boundary. Semantic verification is a dynamic check. It happens against the expected state of the system. The difference is context. Without context, you are just checking syntax.

You need to define the semantic invariants explicitly. What must be true for this data to be valid at this step? Write those down. Turn them into code. That is the real work. The schema is just the skeleton. The assertions are the muscle.

How do I model semantic invariants for complex handoffs?

Start with the state machine. What states can the data be in? What transitions are valid? Map these to the fields in your payload. Then, write assertions that check the current state against the expected state.

For example, if a field is a timestamp, assert that it is in the future relative to the previous step. If a field is a status, assert that it matches the allowed values for the current step. Keep the assertions simple. Complex logic in assertions becomes its own maintenance burden.

Use explicit metadata for units and timezones. Do not rely on convention. Do not rely on the agent to infer context. Make the context part of the data. This reduces ambiguity at the source. It makes the assertions easier to write and easier to debug.

What is the operational cost of maintaining these assertions?

It is low if you keep them simple. It is high if you try to verify everything. The cost is in the writing and the debugging. You need to write the assertions. You need to debug them when they fail.

But the cost of not having them is higher. You are spending time debugging production incidents. You are spending time tracing data through the pipeline. You are spending time explaining to stakeholders why the system is unreliable. The assertions pay for themselves in reduced incident time.

Assign ownership clearly. The team that owns the agent handoff owns the assertions. They are responsible for keeping them in sync with the logic. Do not let the assertions become an orphaned layer. They are part of the contract.

How do I prove this reduces incident rates?

Measure the time-to-halt. Without assertions, the error propagates. You find it at the end. With assertions, the error halts at the boundary. You find it immediately. The difference in debugging time is your proof.

Track the number of incidents caused by inter-agent mismatches. Compare before and after. You should see a drop. You should also see a drop in the severity of the incidents. They are caught earlier, so they are less damaging.

This is the business outcome. Reduced incident rate. Reduced debugging time. Increased release confidence. You can ship changes to the agents with more confidence because you know the handoffs are verified. The system is more operable.

What should I do this week to start?

Pick one high-value handoff. Identify the three most ambiguous fields. Write assertions for them. Run them in shadow mode. Look at the drift log.

You will see the patterns. You will see where the meaning is drifting. You will have data to make the next decision. Do not try to build the whole system. Build the proof. The proof is the first step to a reliable pipeline.

The method is simple. Diagnose the drift. Model the invariants. Build the assertions. Harden the boundaries. Do it one handoff at a time. The system will become more robust as you go. The key is to start. The cost of waiting is the next incident.