pre-alpha · protocol designview on github

Yeon documentation

Yeon is a framework-neutral protocol and Python runtime for typed handoffs between AI agents. It gives different frameworks one document model, lifecycle, and observability surface.

handoff research_company @1
  planner -> researcher

  in
    company: "OpenAI"

  out ResearchReport
  within 30s
Illustrative syntax. The grammar is still being designed.

Why Yeon

Agent frameworks already support structured values. Yeon focuses on the contract between agents: what work was requested, which schemas apply, how execution progresses, and how the outcome is represented across frameworks.

  • Typed: validate inputs and outputs against named schemas.
  • Observable: describe lifecycle changes with structured events.
  • Deterministic: give equivalent documents one canonical representation.
  • Portable: keep documents independent of providers and transports.

Documents

Handoff
A request to run a named target with typed input and expected output.
Result
The successful terminal response to a handoff.
Error
The failed terminal response to a handoff.
Event
A structured observation about the handoff lifecycle.

Representations

Compact Yeon  ↔  document  ↔  canonical JSON

These are three representations of one logical document. Canonical JSON is deterministic and machine-facing. Compact Yeon is optional, LLM-facing, and will remain only if benchmarks show an advantage over JSON.

Schemas

Named, versioned schemas validate inputs before an agent runs and validate outputs before a result is returned. Identity, compatibility, and evolution rules are still being designed.

Local runtime

V1 runs registered agents in one Python process. The runtime validates a handoff, finds its target, executes it, validates the output, and returns a Result or Error.

  1. Receive and validate the Handoff.
  2. Resolve the target in the local agent registry.
  3. Execute with deadlines, cancellation, and retries.
  4. Validate output and emit the terminal document.

Lifecycle

pending  →  running  →  completed | failed | cancelled

The runtime emits structured events for each lifecycle change. CLI logs and traces consume those events now; a future web interface can consume the same stream later.

Integrations

OpenAI, Anthropic, LangChain, LangGraph, MCP, and custom agents connect through adapters. Provider-specific objects stay outside the core document model.

What comes next

Work begins with documents, schemas, the Python SDK, and the local runtime. Canonical JSON, Compact Yeon, CLI tracing, benchmarks, and integrations follow. Persistence, remote workers, durable queues, load balancing, and multi-tenant infrastructure are deferred.

Working notes Yeon home