Skip to content

feat(protocol): agent cards offer trajectory formats, reads may name one, and every answer names its format - #787

Merged
earakely-scale merged 5 commits into
mainfrom
edgararakelyan/fd-6076-y2a-trajectory-formats
Nov 18, 2026
Merged

earakely-scale merged 5 commits into
mainfrom
edgararakelyan/fd-6076-y2a-trajectory-formats

Conversation

@earakely-scale

@earakely-scale earakely-scale commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

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/1 on (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's params, beside methods:

    • formats: what a read may name;
    • native: the native format, which never changes;
    • default: what a read naming no format gets; it equals native until 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 get override included. It gets HTTP 400 with {"ok": false, "error": {"code": "format_not_offered", "message": "... this agent offers <formats>", "retryable": false, "applied": "no"}}. A card without formats refuses every named format.

  • An AgentEnvError from 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's raise_for_extension_status already reads error.code, and a new test checks it names format_not_offered.

  • Every SDK-served response names its format:

    • {trajectory, format} and {objects, format} for task and context reads;
    • the cursor reads already did.
  • 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 names pi-json-events/v1.

  • With native declared, the SDK holds the agent to it:

    • the log starts in that format, so set_format is optional;
    • a set_format or a returned native_trajectory in another format fails the turn as an agent_error with code framework.trajectory_format_mismatch, its message naming both formats. It isn't an unhandled infra_error, which a retry would only repeat. The rule lives in the log alone, and both paths use 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 proxy agent declares native="agentenv-proxy/v1". Its code ships in the protocol package, so it can use native now.

  • Docs:

    • the protocol README gains a "Trajectory formats" section, the error rule for agent handlers, and format in the op table;
    • src/agent_env/agents/AGENTS.md tells agent authors about native=.

Decided

  • The unoffered format's error was the issue's open question for Y2a. Decided 2026-11-18 (FD-6074 decisions, Y2a-1): HTTP 400 with format_not_offered, and AgentEnvError mapped for every agent extension.
    • Rejected: 406, since it's HTTP's Accept-header negotiation.
    • Rejected: 422, a FastAPI convention this SDK doesn't use.
    • Rejected: a detail string, from which agent-env can't read the code.

Not in this PR

  • The built-in agents don't declare native yet. Each image installs the protocol from PyPI at or above its folder's floor, and is rebuilt only when its folder changes. Declaring native needs 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:

    • add native= to each agent's enable (their TRAJECTORY_FORMAT constants);
    • have Claude Code's and Codex's own context reads name their formats (Claude Code's session-derived reads get an id of their own, never native; Decision 3);
    • raise each agent's floor.

    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

  • A request with no format is handled exactly as before.
  • Response bodies gain only the format key; the payload is unchanged. Every agent-env reader ignores extra keys (TrajectoryEventsResponse already had format).
  • Cards now list format among 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 takes format from formats, not from the request schema.
  • A pinned image with an older protocol refuses format, since its request models forbid extra fields. Its card has no formats, so callers send none.

Testing

  • Protocol suite: 1,796 passed, 1 skipped on main with 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:

    • card params with and without native;
    • native validation;
    • named-native and unnamed reads on task, context, cursor and objects reads;
    • the refusal on all six variants, and on a card without formats;
    • an unoffered format never reaching an agent's own handlers;
    • the log held to native;
    • a returned native trajectory keeping its format, with and without native;
    • a set_format or native trajectory in another format failing the turn as an agent_error with framework.trajectory_format_mismatch and both formats in the message;
    • AgentEnvError from an agent's handler, and an opaque 500 still hiding other exceptions;
    • the proxy's card and read.
  • Existing tests updated, payload assertions unchanged:

    • 15 protocol tests and 17 tests in tst/unit/agents/ (Claude Code, Codex, Gemini) pinned exact response bodies or the card's request shape; they now also expect format;
    • no agent folder changes, so no image is rebuilt.
  • Integration (new): test_a_deployed_agent_serves_its_native_format_and_refuses_another deploys the echo agent, which now declares agentenv-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, native and default are on the card;
    • cursor and final reads name the format, with and without naming it;
    • a read naming atif/1 is refused, and raise_for_extension_status reports HTTP 400: format_not_offered.

    The existing live-trajectory test in the same module now runs against an agent with native declared.

  • agent-env unit: tst/unit/a2a_agent/protocol_test.py checks that raise_for_extension_status names format_not_offered from 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 of main's latest run (integration-local 161 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:

    • commands varied events, set_format, native trajectories in matching and other formats, failing and raising turns, and gated turns read mid-run;
    • reads covered all four inline and cursor variants, unknown ids, out-of-range after and limit, and named formats: offered, unoffered, empty and too long.

    Its checks:

    • for every read naming no format, this branch's answer is main's plus format (cursor and own-handler reads unchanged), and format, payloads, pages and task states equal an oracle's;
    • an agent declaring native answers a read naming it exactly like one naming none, and names it on every SDK-served read;
    • every unoffered format is refused with the exact format_not_offered body;
    • an agent's own context handler runs exactly once per read that names no format or an offered one;
    • an AgentEnvError answers 409 with its body where main answered an opaque 500;
    • there are no other 5xx answers.

    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= on enable(TRAJECTORY_V1, ...);
  • formats, native and default on the card;
  • format on reads and in responses;
  • format_not_offered;
  • AgentEnvError from agent handlers.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence 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.

  • Agents can declare a native trajectory format and reject reads that name another format.
  • Trajectory reads can name a format, and the SDK refuses formats the card does not offer.
  • SDK-served trajectory answers name the format of the data they return.
  • Agent extension handlers return their AgentEnvError status and body.

Reviews (7) · Last reviewed commit: "fix(protocol): a trajectory format misma..." · Reviewed by Greptile

…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>
@earakely-scale
earakely-scale requested a review from a team as a code owner November 18, 2026 21:24
earakely-scale and others added 4 commits November 18, 2026 13:29
…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
earakely-scale merged commit 8bd8b18 into main Nov 18, 2026
37 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/fd-6076-y2a-trajectory-formats branch November 18, 2026 23:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant