Skip to content

proto: subagent prompt/history as structured AgentStart fields#1

Open
christopherwxyz wants to merge 1 commit into
mainfrom
upstream-pr/structured-subagent-args
Open

proto: subagent prompt/history as structured AgentStart fields#1
christopherwxyz wants to merge 1 commit into
mainfrom
upstream-pr/structured-subagent-args

Conversation

@christopherwxyz

@christopherwxyz christopherwxyz commented May 24, 2026

Copy link
Copy Markdown

Summary

Replace the planner's synthesized envelope string with two typed
AgentStart proto fields.

message AgentStart {
  string agent_id        = 1;
  bytes  agent_config    = 2;
  repeated Message messages = 3;
  string subagent_prompt  = 4;  // NEW: planner's `prompt` arg verbatim
  string subagent_history = 5;  // NEW: planner's `history` arg verbatim
}

Motivation

The Gemini planner currently synthesizes a multi-line string envelope
as Messages[0]:

History Summary:
<stringified conversation history>

Prompt:
<the planner's `prompt` function-call argument verbatim>

Every subagent that wants clean access to the typed prompt arg has
to string-parse this envelope. Any change to the envelope wording
silently breaks every subagent.

Change

  • Add subagent_prompt (field 4) and subagent_history (field 5) on
    AgentStart. Planner populates them from the typed Gemini
    FunctionCall.Args directly.
  • The planner no longer synthesizes a fake user-role Message. For
    planner-driven dispatch, AgentStart.Messages is empty.
  • Messages remains the wire surface for direct (non-planner)
    callers
    (e.g. grpcurl-driven testing of a subagent).

Breaking change

Subagents that currently read lastUserText(start.Messages) on
planner-driven invocations must migrate to:

prompt := start.GetSubagentPrompt()
if prompt == "" {
    // direct caller path — read from Messages as before
    prompt, _ = lastUserText(start.Messages)
}

The reference python_sandbox_agent example in PR #3 is updated to
this pattern in a sibling commit.

Test coverage

TestHandleSubagentCall_PopulatesStructuredFieldsOnly — asserts:

  1. SubagentPrompt + SubagentHistory populated from typed args
  2. Messages is empty (regression guard against re-introducing the
    envelope)

go test -race ./... clean.

Related

The Gemini planner used to synthesize a multi-line string envelope as
the subagent's first user-role Message:

    History Summary:
    <stringified conversation history>

    Prompt:
    <the planner's `prompt` function-call argument verbatim>

Every subagent that wanted clean access to the planner's typed `prompt`
arg had to string-parse the envelope. Any change to the envelope
wording silently broke every subagent.

This commit replaces the envelope with two new fields on AgentStart:

    string subagent_prompt  = 4;  // planner's `prompt` arg verbatim
    string subagent_history = 5;  // planner's `history` arg verbatim

The planner now populates these structured fields and leaves
AgentStart.Messages empty for planner-driven dispatch. Messages
remains the wire surface for direct (non-planner) callers (e.g.
grpcurl).

This is a BREAKING CHANGE for subagents that currently read
lastUserText(start.Messages) on planner-driven invocations — they
must switch to start.GetSubagentPrompt(). The reference
python_sandbox_agent example is updated in a sibling PR.

Test: TestHandleSubagentCall_PopulatesStructuredFieldsOnly asserts the
structured fields are populated AND AgentStart.Messages is empty (any
"History Summary:\n…\nPrompt:\n…" string showing up in Messages is
now a regression).

go test -race ./... clean.
@christopherwxyz christopherwxyz force-pushed the upstream-pr/structured-subagent-args branch from f76963d to aa0eff0 Compare May 24, 2026 15:13
@christopherwxyz christopherwxyz changed the title proto: pass subagent prompt/history as structured AgentStart fields proto: subagent prompt/history as structured AgentStart fields (BREAKING) May 24, 2026
christopherwxyz added a commit that referenced this pull request May 25, 2026
…earch_agent)

These two examples were Slack-specific / Vertex-specific application
code that has been extracted into the uno-infra monorepo where they
belong (deployed alongside their K8s manifests).

Keeping them in the AX fork's examples/ created merge conflicts on
every upstream pull from google/ax. With them gone, the fork's
divergence from upstream is bounded to:
  - the three PR branches (#1 #2 #3) of generic AX improvements
  - feat/agent-sandbox-backend's tracking branch

examples/python_sandbox_agent/ stays — it's a generic reference
implementation of the agent-sandbox backend pattern, useful upstream.
@christopherwxyz christopherwxyz changed the title proto: subagent prompt/history as structured AgentStart fields (BREAKING) proto: subagent prompt/history as structured AgentStart fields May 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant