Repository navigation
feat(protocol): agent cards offer trajectory formats, reads may name one, and every answer names its format - #787
Merged
earakely-scale merged 5 commits intoNov 18, 2026
Conversation
…one, and every answer names its format enable(TRAJECTORY_V1, native=...) lists formats, native and default on the card. Every trajectory read takes an optional format; one the card doesn't offer is refused with HTTP 400 format_not_offered before any handler runs. An AgentEnvError from any agent extension handler now answers with its status and the env servers' error body instead of an opaque 500. SDK-served reads name the format they served, a returned native_trajectory keeps its format at seal (pi's null label), and a declared native format holds the log and native trajectories to it. The proxy declares agentenv-proxy/v1. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…and refuses another The echo agent declares agentenv-echo-agent/v1 as its native format; an integration test deploys it on a local sandbox, runs a turn, and reads its card and trajectory over HTTP: formats, native and default on the card, the format named on cursor and final reads, and a read naming another format refused with format_not_offered, which agent-env's raise_for_extension_status reports. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…al format and the served format Claude Code's, Codex's and Gemini's unit tests pinned the trajectory request shape and the bodies of SDK-served reads exactly; the request now lists the optional format, and each read names the agent's TRAJECTORY_FORMAT. The payloads are unchanged. No agent folder changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nt's error, and the objects answer's model names its format With a native format declared, a set_format or returned native trajectory in another format raised past the agent and ended the turn as framework.unhandled_exception, an infra_error a retry repeats. It now fails the turn as an agent_error with code framework.trajectory_format_mismatch, its message naming both formats. The rule lives in the log alone: set_format and the executor's check of a returned native trajectory share it, and the seal no longer repeats it. TrajectoryObjectsResponse gains format and builds the SDK's objects answer, so the published model matches the wire; a request's format refuses a blank id, as native and set_format do; the byte-identity test reuses _grant(). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
earakely-scale
deleted the
edgararakelyan/fd-6076-y2a-trajectory-formats
branch
November 18, 2026 23:02
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Y2a of FD-6076: the trajectory extension's format contract, with no new format. A card can now say which trajectory formats it serves, a read can name one, and every response the SDK answers says which format it served. This is the base Y2b builds
atif/1on (FD-6074, Decision 3).What changes
enable(TRAJECTORY_V1, live=..., native="<format id>")declares the native trajectory's format. The card then lists three fields in the trajectory extension'sparams, besidemethods:formats: what a read may name;native: the native format, which never changes;default: what a read naming no format gets; it equalsnativeuntil F10 (FD-6096).Only AgentCards change. The gateway's EnvironmentCard trajectory entry is untouched.
Every trajectory request takes an optional
format, on all six variants. A read naming none is served as it is today.A read naming a format the card doesn't offer is refused before any handler runs, the agent's own context handlers and a full
getoverride included. It gets HTTP 400 with{"ok": false, "error": {"code": "format_not_offered", "message": "... this agent offers <formats>", "retryable": false, "applied": "no"}}. A card withoutformatsrefuses every named format.An
AgentEnvErrorfrom any agent extension handler now answers with its status and that body, as env servers already do. Today it becomes an opaque 500. agent-env'sraise_for_extension_statusalready readserror.code, and a new test checks it namesformat_not_offered.Every SDK-served response names its format:
{trajectory, format}and{objects, format}for task and context reads;A returned
native_trajectory's format is kept at seal and named in final reads. This fixes pi's null label: its final read now namespi-json-events/v1.With
nativedeclared, the SDK holds the agent to it:set_formatis optional;set_formator a returnednative_trajectoryin another format fails the turn as anagent_errorwith codeframework.trajectory_format_mismatch, its message naming both formats. It isn't an unhandledinfra_error, which a retry would only repeat. The rule lives in the log alone, and both paths use it.TrajectoryObjectsResponsegainsformatand builds the SDK's objects answer, so the published model matches the wire. A request'sformatrefuses a blank id, asnativeandset_formatdo.The proxy agent declares
native="agentenv-proxy/v1". Its code ships in the protocol package, so it can usenativenow.Docs:
formatin the op table;src/agent_env/agents/AGENTS.mdtells agent authors aboutnative=.Decided
format_not_offered, andAgentEnvErrormapped for every agent extension.Accept-header negotiation.detailstring, from which agent-env can't read the code.Not in this PR
The built-in agents don't declare
nativeyet. Each image installs the protocol from PyPI at or above its folder's floor, and is rebuilt only when its folder changes. Declaringnativeneeds a floor that has it, and no earlier PR has raised a floor to an unreleased version. So a follow-up after this protocol release will:native=to each agent'senable(theirTRAJECTORY_FORMATconstants);native; Decision 3);That follow-up closes the issue's two built-in-agent checks: every built-in agent names its format, and pi's deployed image reports
pi-json-events/v1.Y2b (serving
atif/1) needs Y1a (feat(protocol): ATIF in agentenv_protocol: Harbor's models vendored, the agentenv profile and the adapter framework (Y1a, FD-6075) #778) and Y1b.Compatibility
formatis handled exactly as before.formatkey; the payload is unchanged. Every agent-env reader ignores extra keys (TrajectoryEventsResponsealready hadformat).formatamong the trajectory request's optional fields. agent-env picks a variant by required fields only (card_request_accepts), so negotiation is unchanged. Callers tell whether a card takesformatfromformats, not from the request schema.format, since its request models forbid extra fields. Its card has noformats, so callers send none.Testing
Protocol suite: 1,796 passed, 1 skipped on
mainwith feat(protocol): ATIF in agentenv_protocol: Harbor's models vendored, the agentenv profile and the adapter framework (Y1a, FD-6075) #778 merged, 20 of them new tests:native;nativevalidation;formats;native;native;set_formator native trajectory in another format failing the turn as anagent_errorwithframework.trajectory_format_mismatchand both formats in the message;AgentEnvErrorfrom an agent's handler, and an opaque 500 still hiding other exceptions;Existing tests updated, payload assertions unchanged:
tst/unit/agents/(Claude Code, Codex, Gemini) pinned exact response bodies or the card's request shape; they now also expectformat;Integration (new):
test_a_deployed_agent_serves_its_native_format_and_refuses_anotherdeploys the echo agent, which now declaresagentenv-echo-agent/v1, on a local sandbox and runs a turn. It then reads the deployed agent's card and trajectory over HTTP with its control token:formats,nativeanddefaultare on the card;atif/1is refused, andraise_for_extension_statusreportsHTTP 400: format_not_offered.The existing live-trajectory test in the same module now runs against an agent with
nativedeclared.agent-env unit:
tst/unit/a2a_agent/protocol_test.pychecks thatraise_for_extension_statusnamesformat_not_offeredfrom a real SDK agent.CI time: the new integration test takes about 18 s on one xdist worker of
integration-local. Every job was within runner noise ofmain's latest run (integration-local161 s against 208 s), so this PR doesn't lengthen e2e CI.e2e on a test host (x86_64, Docker): the live-trajectory integration module from 83bde4e passed, 2 tests in 64 s. The arm64 host can't run it, because the echo agent's base image is pinned to an amd64-only digest. That predates this PR.
Chaos on a test host (arm64, 25 minutes, 31,793 scripts, 1,180,162 reads, 0 failures). Random task scripts were played against agent servers on
main's protocol and this branch's:set_format, native trajectories in matching and other formats, failing and raising turns, and gated turns read mid-run;afterandlimit, and named formats: offered, unoffered, empty and too long.Its checks:
main's plusformat(cursor and own-handler reads unchanged), andformat, payloads, pages and task states equal an oracle's;nativeanswers a read naming it exactly like one naming none, and names it on every SDK-served read;format_not_offeredbody;AgentEnvErroranswers 409 with its body wheremainanswered an opaque 500;Four planted bugs were each caught in under 10 seconds: the native format dropped at seal, the check skipped for agent-bound handlers, the check always passing, and the log not starting in the native format. Objects reads aren't in the chaos run, since they need a write grant; unit tests cover them.
Matrix on the arm64 host: the a2a trajectory, agent, object-transfer and proxy tests against the installed wheel pass, 255 each, at Python 3.10 with pydantic 2.11.10 and at 3.13 with 2.14.3.
Greptile 5/5 on d4b6695. Its one comment, the format id's length limit written twice, is fixed and resolved.
ruff check .passes.For the docs site
The agent extension pages should cover:
native=onenable(TRAJECTORY_V1, ...);formats,nativeanddefaulton the card;formaton reads and in responses;format_not_offered;AgentEnvErrorfrom agent handlers.🤖 Generated with Claude Code


Confidence Score: 5/5
The reviewed changes appear safe to merge; no new blocking issues were found.Summary
Adds trajectory format discovery, optional format selection on reads, and format labels on SDK responses. The follow-up changes make format mismatches fail as agent errors and align the objects response model with the wire.
AgentEnvErrorstatus and body.Reviews (7) · Last reviewed commit: "fix(protocol): a trajectory format misma..." · Reviewed by Greptile