Structured Handoff for AI Agents

Agents hand off work as typed blocks that any orchestrator parses deterministically — with revisions, fix cycles and a validated state machine.

7 Block types

5/5 Conformance chains

Read Documentation View GitHub

[ARCH:PLAN]

id:api|fw:python

[BUILD:EXEC]

id:m1|target:main

[TEST:RUN]

id:t1|cmd:pytest

Why H2C Exists

⚡

Ambiguous Handoffs

Agents pass state as prose and the next agent guesses. H2C makes every handoff a typed, validated block.

🔗

No Structured Protocol

AI agents communicate in unstructured text. H2C provides typed, parseable blocks.

📦

Context Collapse

Long chains accumulate stale context with no signal of what to drop. H2C's PRUNE, COMPACT and FREEZE blocks make that explicit.

🔄

Silent Failures

Malformed or out-of-order messages fail silently or get guessed at. H2C's reference validator and state machine reject invalid blocks and transitions with explicit diagnostics.

🤝

No Versioned Handoff

Agents can't resume conversations. H2C includes cycle tracking and versioning.

🎯

Agent Orchestration

Building multi-agent systems requires custom protocols. H2C is a standard wire format.

Core Features

📝

Structured Grammar

Formal BNF grammar with typed fields, lists, and revisions. Self-describing blocks that LLMs parse natively.

🚀

Deterministic Parsing

One grammar, one parser, explicit diagnostics. Round-trip lossless on the reference fixtures.

🔌

Universal Transport

Agnostic to transport: stdin/stdout, HTTP, WebSocket, MCP. Integrate with any framework.

🎛️

Context Management

PRUNE, COMPACT, FREEZE commands mark what can be dropped from long agent chains.

📊

Agent Orchestration

Built-in cycle tracking, retry counters, and versioned handoff. Versioning-aware agent choreography.

✅

Validated State Machine

Every block and transition is checked by the reference validator and finite-state machine — invalid states surface as explicit diagnostics, not silent failures.

Measured, not estimated

Scenario	Natural language	H2C	Delta
Hello World	131 tokens	204 tokens	+56%
Calculator	300 tokens	434 tokens	+45%
Clean Arch	536 tokens	922 tokens	+72%
RAG Pipe	800 tokens	1323 tokens	+65%

Measured with tiktoken o200k_base. H2C costs more tokens because it carries explicit state. Reproduce: python3 conformance/benchmark.py fixtures

Use Cases

Multi-Agent Orchestration

Architect → Builder → Tester pipelines with retry tracking and versioned handoff.

Long-Running Chains

100+ message conversations with intelligent pruning, compaction, and freezing.

LLM-to-LLM Handoff

Structured output from Agent A → direct consumption by Agent B, no parsing overhead.

Cognitive IR

Structured handoff blocks for retrieval-augmented generation and reasoning transport.

Agent Runtime Protocol

Standard wire format for agent hosting platforms and orchestration frameworks.

Framework Integration

Drop-in layer for LangGraph, AutoGen, CrewAI, Semantic Kernel, and MCP.

Core Syntax

Minimal H2C Example

A structured block replaces a prose description with explicit, versioned fields.

This minimal example shows how H2C blocks replace verbose AI communication with clean, typed fields.

[ARCH:PLAN]
id:api-weather|fw:python3.11|lib:fastapi,httpx|auth:APIKey|struct:[main.py,services/weather.py]

[BUILD:EXEC]
id:m1|target:main.py|desc:setup_fastapi_app

[BUILD:DONE]
id:m1|diff:[main.py~1]|rev:1

[ORCH:END]
final:complete|est_token:15

Real-World Examples

Validated chain

🌤️ Weather API Service

Python FastAPI service with caching, rate limiting, and multi-step build orchestration.

Validated chain

📝 TODO Console App

C# .NET 8 application with SQLite, demonstrating H2C in stateful, long-running workflows.

Validated chain

🔄 PRUNE/COMPACT Chain

Complete v1.4 workflow with context management and a CTX:NEGOTIATE handshake.

Conformance chain

🧪 Conformance Stress Test

130-message fixture that exercises PRUNE, COMPACT, and FREEZE through the reference parser, validator, and state machine.

Challenge

Building a Python FastAPI weather service with caching, rate limiting, and multi-step orchestration requires multiple coordination steps and verbose documentation in natural language.

H2C Solution

[ARCH:PLAN]
id:weather-api|fw:python3.11|lib:[fastapi,httpx,cachetools]
auth:APIKey::env(OPENWEATHER_API_KEY)
struct:[main.py,routers/weather.py,services/weather_service.py]
notes:[cache_TTL_10min,rate-limit_60req-min]

[BUILD:EXEC]
id:m1|target:main.py|desc:setup_fastapi_app

[BUILD:DONE]
id:m1|diff:[main.py~1]|rev:1

[TEST:RUN]
id:test_weather|cmd:pytest tests/test_weather.py

[TEST:PASS]
id:test_weather|pass_count:42

[ORCH:END]
final:complete|est_token:2450

Impact

✅ Maintains all architectural metadata
✅ Machine-parseable for agent coordination
✅ Scales to multi-agent workflows

Challenge

C# .NET 8 console application with SQLite backend demonstrates how H2C handles stateful, long-running workflows with multiple state transitions and persistent queries.

H2C Solution

[ARCH:PLAN]
id:todo-app|fw:dotnet8|db:sqlite|lib:[EFCore,Spectre.Console]
struct:[Program.cs,Models/,Services/,Data/]

[CTX:UPDATE]
~progress:layer=init,status=in_progress
~next:database_setup
~active_files:[Program.cs~1]

[BUILD:EXEC]
id:b1|target:Program.cs|desc:setup_dependency_injection

[CTX:UPDATE]
~progress:layer=database,status=done
~next:crud_implementation
~active_files:[Program.cs~1,Data/TodoContext.cs~1]

[TEST:RUN]
id:t1|cmd:dotnet test TodoServiceTests.cs

[ORCH:END]
final:complete|est_token:1845

Impact

✅ Clear cycle tracking for debugging
✅ Persistent state management
✅ Cost-effective for long-running apps

Challenge

Long-running chains carry context blocks (PRUNE, COMPACT, FREEZE) that mark what can be dropped.

H2C Solution

[BUILD:DONE]
id:b1|diff:[src/main.py~1]|rev:5

[BUILD:DONE]
id:b2|diff:[src/utils.py~2]|rev:3

[CTX:PRUNE]
keep:[b1,b2]|pruned:[b1,b2]|reason:consolidate_old_builds

[BUILD:DONE]
id:b3|diff:[src/api.py~1]|rev:1

[CTX:COMPACT]
summary:[layer=3,status=done,files:[src/main.py~5,src/utils.py~3,src/api.py~1]]
keep_active:[src/api.py~1]
pruned_history:msg_2_to_5

[ORCH:END]
final:complete|est_token:7140

Impact

✅ CTX:PRUNE and CTX:COMPACT keep only active files in scope
✅ Scales to multi-week workflows

H2C Code Examples

See how H2C blocks replace verbose natural language

ARCH

[ARCH:PLAN]
id:weather-api
fw:python3.11
lib:[fastapi,httpx,cachetools]
auth:APIKey::env(OPENWEATHER_API_KEY)
struct:[main.py,routers/weather.py,services/weather_service.py]
notes:[cache_TTL_10min,rate-limit_60req-min]

Architecture plan with framework, libraries, auth, and structure

BUILD

[BUILD:EXEC]
id:m1
target:main.py
desc:setup_fastapi_app

[BUILD:DONE]
id:m1
diff:[main.py~1]
rev:1

Build execution and completion with revision tracking

TEST

[TEST:RUN]
id:test_weather_endpoint
cmd:pytest tests/test_weather.py

[TEST:PASS]
id:test_weather_endpoint
pass_count:42

Test execution with results and pass count

CTX

[CTX:UPDATE]
~progress:layer=data,status=in_progress
~next:database_setup
~active_files:[main.py~1,models.py~1]

Context update with layer tracking and active files

CTX

[CTX:PRUNE]
keep:[m3,m4,t1]|pruned:[m1,m2]|reason:builds_completed

[CTX:COMPACT]
summary:[layer=api,status=done,files:[auth.py~1,routes.py~1]]
keep_active:[auth.py~1,routes.py~1]
pruned_history:msg_2_to_19

Context pruning and compaction for long-running chains

ORCH

[ORCH:END]
final:complete
est_token:15420
pass_count:42
fail_count:2

Orchestration completion with token estimate and counters

Natural Language vs H2C

❌ Natural Language

I've set up a new FastAPI weather service
using Python 3.11. The service includes
multiple endpoints for weather data fetching
with caching (10 minute TTL) and rate limiting
at 60 requests per minute. I've structured
the code with separate routers and service
layers. Authentication is handled via API key
stored in environment variables...

✅ H2C

[ARCH:PLAN]
id:weather-api|fw:python3.11
lib:[fastapi,httpx,cachetools]
auth:APIKey::env(OPENWEATHER_API_KEY)
struct:[main.py,routers/,services/]
notes:[cache_TTL_10min,rate-limit_60req-min]

Result: explicit, typed fields instead of prose — parsed deterministically, not interpreted

Project Roadmap

✓

v1.0 - Core Grammar

Foundational blocks, base syntax

Released

✓

v1.1 - Context Management

PRUNE/COMPACT, revisions, counters

Released

✓

v1.2 - State Machine

FREEZE, cycle tracking, retry logic

Released

✓

v1.3 - Formal Specification

EBNF ISO 14977, AST model, opcodes

Released

✓

v1.4 - Handshake & Error Recovery

CTX:NEGOTIATE handshake, BUILD:NACK, DAG transitive closure, formal STATE:FINDINGS

Released

→

v2.0 - Reference Implementation

Parser, validator, transpiler

Planned

🔬

v3.0 - Runtime & Compiler

Native MCP transport, agent runtime

Research

Ecosystem Integration

H2C works as the structured handoff layer for your favorite frameworks

🔌

MCP

Transport H2C blocks via MCP tool calls

🔀

LangGraph

H2C as node output format and state schema

🤖

AutoGen

H2C as agent response protocol

⚙️

Semantic Kernel

H2C for function result serialization

👥

CrewAI

H2C as task output format

🎯

OpenAI Agents SDK

H2C as structured output format

Frequently Asked Questions

Is H2C the same as HTTP/2 h2c? +

No. H2C is a structured handoff protocol for AI-to-AI communication, completely unrelated to the HTTP/2 cleartext upgrade mechanism defined in RFC 7540. The name stands for "Human-to-Compiler" / "Head-to-Core" — a structured format for AI agent handoff, not a network protocol. If you're looking for HTTP/2 h2c, see RFC 7540.

Does H2C save tokens? +

No, and we measured it. With tiktoken (o200k_base), H2C chains use more tokens than an equivalent natural-language brief on our reference scenarios, because they carry explicit state: ids, revisions, cycle ids. H2C's value is deterministic parsing and versioned handoff, not size. Reproduce with python3 conformance/benchmark.py fixtures.

Which LLMs does H2C support? +

H2C is plain text with a small grammar, so any model can read and write it; the reference parser and validator make every handoff checkable regardless of which model produced it. We have not published a cross-model benchmark yet.

Do I need any dependencies or libraries to use H2C? +

No. H2C is a plain-text protocol with a formal BNF grammar. You can use it immediately with any LLM — no libraries, no SDK, no runtime. Simply include the H2C grammar in your system prompt, and both you and the AI can start exchanging H2C blocks right away. A reference parser, validator, and transpiler are planned for v2.0.

How does H2C compare to JSON or YAML for AI agents? +

H2C is purpose-built for AI-to-AI communication, unlike JSON or YAML which are general-purpose serialization formats. Key differences: (1) H2C blocks include built-in semantics for versioning (rev:), cycle tracking (cycle:), and context management (PRUNE, COMPACT, FREEZE) that JSON/YAML lack; (2) LLMs produce valid H2C more reliably because the grammar is optimized for token prediction, not human readability; (3) H2C is designed to be self-describing and self-documenting, reducing the parsing overhead that makes JSON verbose.

Ready to Structure Your Agent Handoffs?

H2C is open-source (MIT), requires zero dependencies, and works with any LLM with an 8K+ context window.

Read Full Documentation Clone on GitHub

Structured Handoff for AI Agents

Why H2C Exists

Ambiguous Handoffs

No Structured Protocol

Context Collapse

Silent Failures

No Versioned Handoff

Agent Orchestration

Core Features

Structured Grammar

Deterministic Parsing

Universal Transport

Context Management

Agent Orchestration

Validated State Machine

Measured, not estimated

Use Cases

Multi-Agent Orchestration

Long-Running Chains

LLM-to-LLM Handoff

Cognitive IR

Agent Runtime Protocol

Framework Integration

Core Syntax

Minimal H2C Example

Real-World Examples

🌤️ Weather API Service

📝 TODO Console App

🔄 PRUNE/COMPACT Chain

🧪 Conformance Stress Test

🌤️ Weather API Service

Challenge

H2C Solution

Impact

📝 TODO Console App

Challenge

H2C Solution

Impact

🔄 PRUNE/COMPACT Chain

Challenge

H2C Solution

Impact

🧪 Conformance Stress Test

Challenge

Key Findings

H2C Code Examples

Natural Language vs H2C

❌ Natural Language

✅ H2C

Project Roadmap

v1.0 - Core Grammar

v1.1 - Context Management

v1.2 - State Machine

v1.3 - Formal Specification

v1.4 - Handshake & Error Recovery

v2.0 - Reference Implementation

v3.0 - Runtime & Compiler

Ecosystem Integration

MCP

LangGraph

AutoGen

Semantic Kernel

CrewAI

OpenAI Agents SDK

Frequently Asked Questions

Ready to Structure Your Agent Handoffs?