Structured Handoff for AI Agents

H2C gives AI agents a shared text format for handing off tasks. Its typed blocks carry state and results that a parser can validate.

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

When agents pass state as prose, the next agent must infer what it means. H2C puts each handoff in a typed block that tools can validate.

🔗

No Structured Protocol

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

📦

Context Collapse

Long conversations collect details that are no longer useful. PRUNE, COMPACT and FREEZE mark what to keep, summarize or set aside.

🔄

Silent Failures

The reference validator checks block syntax and workflow transitions. It reports invalid input instead of silently guessing.

🤝

No Versioned Handoff

Revision and cycle fields help agents track changes and resume a workflow.

🎯

Agent Orchestration

H2C provides one text format for passing work between agents and orchestration tools.

Core Features

📝

Structured Grammar

A formal grammar defines typed fields, lists and revisions. Blocks are readable as plain text.

🚀

Deterministic Parsing

The reference parser checks blocks against one grammar and reports errors. It also round-trips the published fixtures.

🔌

Universal Transport

H2C is plain text, so applications can send it over HTTP, WebSocket, MCP or standard input and output.

🎛️

Context Management

PRUNE, COMPACT and FREEZE mark context to keep, summarize or set aside in a long workflow.

📊

Agent Orchestration

Cycles, retry counts and revisions make the progress of a handoff explicit.

✅

Validated State Machine

The reference validator and state machine check blocks and transitions. Invalid states produce diagnostics.

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 uses plain text and a published grammar, so it can be used with different language models. The reference parser can check the resulting blocks. No cross-model benchmark has been published.

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

No. H2C is a plain-text protocol with a formal grammar. You can write blocks without an SDK or runtime. A reference parser and validator are available in the project repository.

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?