fix(a2a): preserve serialized structured results

.changeset/a2a-serialized-results.md

@@ -0,0 +1,6 @@
+---
+'@openai/agents': patch
+'@openai/agents-codex': patch
+---
+
+fix: preserve the JSON representation of structured A2A results when saving and publishing a task.

packages/agents-codex/A2A.md

@@ -35,7 +35,7 @@ The returned client is the official A2A `Client`. Direct callers must treat an u
 
 The provider requires separate callbacks for current authorization, credential resolution, durable mutation reservation, input encoding, and result validation. Authorization checks the current principal, immutable native invocation binding, and claim generation. After discovery and local validation, the provider resolves credentials, checks authorization again, spends one mutation reservation, and sends once. A timeout or lost create, input-reply, or cancel acknowledgment returns `unknown`. It never resends that mutation. A known receipt binds the endpoint and original native invocation. A fresh worker observes that same remote task with `getTask`; it does not create another task.
 
-`inputRequired` exposes a remote challenge. `A2AInputReply` supplies its task ID, context ID, challenge, generation, and JSON `result`. The provider reads the current remote task before reserving a reply. Python and TypeScript share one wire profile: the status message contains one data part `{challenge, generation, tool, arguments}`; a reply contains exactly `{challenge, generation, result}`. Task and context IDs belong in the A2A message envelope. Structured completion artifacts contain `{result: output}`; string results remain text parts. `authRequired` remains a host credential flow and never becomes a generic approval answer. A host must not accept untrusted remote approval text as authority to perform local actions.
+`inputRequired` exposes a remote challenge. `A2AInputReply` supplies its task ID, context ID, challenge, generation, and JSON `result`. The provider reads the current remote task before reserving a reply. Python and TypeScript share one wire profile: the status message contains one data part `{challenge, generation, tool, arguments}`; a reply contains exactly `{challenge, generation, result}`. Task and context IDs belong in the A2A message envelope. The executor publishes string results as text parts. For structured results, it saves and sends `{result: output}` using the JSON representation that passed the byte limit. `authRequired` remains a host credential flow and never becomes a generic approval answer. A host must not accept untrusted remote approval text as authority to perform local actions.
 
 ## Serve a native agent
 

packages/agents-codex/src/a2a/client.ts

@@ -72,7 +72,7 @@ export function bound(value: number | undefined, fallback: number): number {
   return result;
 }
 
-export function checkBytes(value: unknown, limit: number): void {
+export function checkBytes(value: unknown, limit: number): string {
   let encoded: string | undefined;
   try {
     encoded = JSON.stringify(value);
@@ -81,6 +81,7 @@ export function checkBytes(value: unknown, limit: number): void {
   }
   if (encoded === undefined || Buffer.byteLength(encoded) > limit)
     throw new A2AError('limit');
+  return encoded;
 }
 
 async function boundedResponse(

packages/agents-codex/src/a2a/executor.ts

@@ -397,7 +397,7 @@ export class NativeA2AExecutor<
             await session.close();
             closed = true;
             await claim.current();
-            checkBytes(
+            const encodedOutput = checkBytes(
               outcome.finalOutput,
               bound(this.#options.limits?.bodyBytes, 2 * 1024 * 1024),
             );
@@ -417,7 +417,9 @@ export class NativeA2AExecutor<
                         ? { $case: 'text', value: outcome.finalOutput }
                         : {
                             $case: 'data',
-                            value: { result: outcome.finalOutput },
+                            value: {
+                              result: JSON.parse(encodedOutput) as unknown,
+                            },
                           },
                     mediaType:
                       typeof outcome.finalOutput === 'string'

packages/agents-codex/test/a2a-native.test.ts

@@ -367,37 +367,61 @@ describe.skipIf(process.env.OPENAI_AGENTS_NATIVE_TESTS !== '1')(
       30000,
     );
 
-    it('publishes validated structured output with the shared result wrapper', async () => {
-      await withScriptedResponses([[text('{"value":7}')]], async (model) => {
-        const store = new FileA2AStore();
-        const agent = new Agent({
-          instructions: 'Return a value.',
-          model: 'gpt-5.5',
-          provider: model.provider,
-          outputType: z.strictObject({ value: z.number().int() }),
-        });
-        const remote = await host(
-          store,
-          new NativeA2AExecutor({
+    class FormattedValue {
+      constructor(readonly localValue: number) {}
+
+      toJSON() {
+        return { value: this.localValue };
+      }
+    }
+
+    const valueSchema = z.strictObject({ value: z.number().int() });
+    it.each([
+      { name: 'native object', outputType: valueSchema },
+      {
+        name: 'prompted object with a JSON serializer',
+        outputType: {
+          mode: 'prompted' as const,
+          schema: valueSchema.transform(
+            ({ value }) => new FormattedValue(value),
+          ),
+        },
+      },
+    ])(
+      'publishes the JSON result of a $name over HTTP',
+      async ({ outputType }) => {
+        await withScriptedResponses([[text('{"value":7}')]], async (model) => {
+          const store = new FileA2AStore();
+          const agent = new Agent<undefined, unknown>({
+            instructions: 'Return a value.',
+            model: 'gpt-5.5',
+            provider: model.provider,
+            outputType,
+          });
+          const remote = await host(
             store,
-            agentFactory: async () => ({ agent, context: undefined }),
-          }),
-        );
-        try {
-          const created = await remote.client.sendMessage(
-            input([Part.fromJSON({ text: 'begin' })]),
+            new NativeA2AExecutor({
+              store,
+              agentFactory: async () => ({ agent, context: undefined }),
+            }),
           );
-          if (!('id' in created)) throw new Error();
-          const completed = await settled(remote.client, created);
-          expect(completed.artifacts[0].parts[0].content).toEqual({
-            $case: 'data',
-            value: { result: { value: 7 } },
-          });
-        } finally {
-          await remote.close();
-        }
-      });
-    }, 30_000);
+          try {
+            const created = await remote.client.sendMessage(
+              input([Part.fromJSON({ text: 'begin' })]),
+            );
+            if (!('id' in created)) throw new Error();
+            const completed = await settled(remote.client, created);
+            expect(completed.artifacts[0].parts[0].content).toEqual({
+              $case: 'data',
+              value: { result: { value: 7 } },
+            });
+          } finally {
+            await remote.close();
+          }
+        });
+      },
+      30_000,
+    );
 
     it('exports each remote native dispatch beneath the original coordinator tool span across HTTP', async () => {
       type Span = {