feat(sdk): add cloud agent A2A helpers

Build provider-neutral A2A message/send payloads from returned cloudAgent metadata and support injected transports for signed AgentCore follow-up calls.

Author: vamgan

README.md

@@ -44,6 +44,26 @@ await client.close();
 
 `context` is caller-defined metadata. AgentDispatch stores and forwards it; your runtime decides what to do with it. It is the right place for repo names, issue IDs, branch names, priority, user preferences, or other task-specific hints.
 
+## Continue with A2A
+
+When the runtime returns `cloudAgent.protocol === "a2a"`, the SDK can turn that handoff metadata into a JSON-RPC `message/send` follow-up request. For AWS AgentCore, pass the generated request through a SigV4/AWS SDK transport in your app or agent framework:
+
+```ts
+import { sendCloudAgentA2AMessage } from "@agent-dispatch/sdk";
+
+const response = await sendCloudAgentA2AMessage(
+  task.cloudAgent!,
+  { text: "Continue the investigation and focus on IAM findings." },
+  async (request) => {
+    // Sign and send `request.url`, `request.headers`, and `request.body`
+    // with your provider-specific client.
+    return signedAgentCoreFetch(request);
+  }
+);
+
+console.log(response.text);
+```
+
 If you already have an MCP transport in your agent framework, use `AgentDispatchMcpClient` directly:
 
 ```ts

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-dispatch/sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "TypeScript SDK for AgentDispatch.",
   "type": "module",
   "license": "Apache-2.0",

package.json

@@ -2,6 +2,7 @@ import type {
   AccountProfile,
   AdapterCapability,
   CancelResult,
+  CloudAgentInteraction,
   DispatchRequest,
   LogChunk,
   TaskHandle,
@@ -80,6 +81,39 @@ export interface AgentDispatchStdioClientOptions extends StdioServerParameters {
   clientVersion?: string;
 }
 
+export interface A2AMessagePart {
+  kind: "text" | (string & {});
+  text?: string;
+  [key: string]: unknown;
+}
+
+export interface CloudAgentA2AMessage {
+  id?: string;
+  role?: "user" | "agent" | (string & {});
+  text?: string;
+  parts?: A2AMessagePart[];
+  messageId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CloudAgentA2AHttpRequest {
+  url: string;
+  method: "POST";
+  headers: Record<string, string>;
+  body: string;
+  cloudAgent: CloudAgentInteraction;
+}
+
+export interface CloudAgentA2AResult {
+  raw: unknown;
+  text?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export type CloudAgentA2ATransport =
+  | ((request: CloudAgentA2AHttpRequest) => Promise<unknown>)
+  | { send(request: CloudAgentA2AHttpRequest): Promise<unknown> };
+
 export interface SpawnCloudAgentRequest {
   instruction: string;
   runtime?: string;
@@ -194,6 +228,68 @@ export function connectAgentDispatchStdioClient(options: AgentDispatchStdioClien
   return AgentDispatchStdioClient.connect(options);
 }
 
+export function createA2AMessageSendPayload(message: CloudAgentA2AMessage): Record<string, unknown> {
+  const parts = message.parts ?? (message.text !== undefined ? [{ kind: "text", text: message.text }] : undefined);
+  if (!parts?.length) {
+    throw new Error("A2A follow-up requires message.text or message.parts.");
+  }
+
+  return {
+    jsonrpc: "2.0",
+    id: message.id ?? createClientId("a2a"),
+    method: "message/send",
+    params: {
+      message: {
+        role: message.role ?? "user",
+        parts,
+        messageId: message.messageId ?? createClientId("msg")
+      },
+      ...(message.metadata ? { metadata: message.metadata } : {})
+    }
+  };
+}
+
+export function createCloudAgentA2AHttpRequest(cloudAgent: CloudAgentInteraction, message: CloudAgentA2AMessage): CloudAgentA2AHttpRequest {
+  if (cloudAgent.protocol !== "a2a") {
+    throw new Error(`Cloud agent protocol is ${cloudAgent.protocol}, not a2a.`);
+  }
+  const url = stringValue(cloudAgent.a2a?.endpointUrl) ?? stringValue(cloudAgent.invocation?.runtimeUrl);
+  if (!url) {
+    throw new Error("Cloud agent A2A endpoint URL is missing.");
+  }
+  const sessionHeaderName = stringValue(cloudAgent.a2a?.sessionHeaderName) ?? stringValue(cloudAgent.invocation?.sessionHeaderName);
+  const sessionHeaderValue = stringValue(cloudAgent.a2a?.sessionHeaderValue) ?? stringValue(cloudAgent.invocation?.sessionHeaderValue);
+  const payload = createA2AMessageSendPayload(message);
+  const method = stringValue(cloudAgent.a2a?.messageMethod) ?? "message/send";
+  payload.method = method;
+
+  const headers: Record<string, string> = {
+    "content-type": stringValue(cloudAgent.invocation?.contentType) ?? "application/json",
+    accept: stringValue(cloudAgent.invocation?.accept) ?? "application/json"
+  };
+  if (sessionHeaderName && sessionHeaderValue) {
+    headers[sessionHeaderName] = sessionHeaderValue;
+  }
+
+  return {
+    url,
+    method: "POST",
+    headers,
+    body: JSON.stringify(payload),
+    cloudAgent
+  };
+}
+
+export async function sendCloudAgentA2AMessage(
+  cloudAgent: CloudAgentInteraction,
+  message: CloudAgentA2AMessage,
+  transport: CloudAgentA2ATransport
+): Promise<CloudAgentA2AResult> {
+  const request = createCloudAgentA2AHttpRequest(cloudAgent, message);
+  const raw = typeof transport === "function" ? await transport(request) : await transport.send(request);
+  return decodeA2AResult(raw);
+}
+
 function removeUndefinedValues(input: Record<string, unknown>): Record<string, unknown> {
   return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
 }
@@ -228,3 +324,32 @@ function isTextContentResult(result: unknown): result is { content: Array<{ type
       Array.isArray((result as { content?: unknown }).content)
   );
 }
+
+function decodeA2AResult(raw: unknown): CloudAgentA2AResult {
+  const candidate = isRecord(raw) && isRecord(raw.result) ? raw.result : raw;
+  const message = isRecord(candidate) && isRecord(candidate.message) ? candidate.message : candidate;
+  const parts = isRecord(message) && Array.isArray(message.parts) ? message.parts : [];
+  const text = parts
+    .filter(isRecord)
+    .map((part) => typeof part.text === "string" ? part.text : "")
+    .filter(Boolean)
+    .join("\n") || undefined;
+  const metadata = isRecord(message) && isRecord(message.metadata)
+    ? message.metadata
+    : isRecord(candidate) && isRecord(candidate.metadata)
+      ? candidate.metadata
+      : undefined;
+  return { raw, text, metadata };
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function createClientId(prefix: string): string {
+  return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}

src/index.ts

@@ -1,6 +1,16 @@
 import { describe, expect, it } from "vitest";
 import type { DispatchRequest, TaskRecord } from "@agent-dispatch/core";
-import { AgentDispatchClient, AgentDispatchMcpClient, AgentDispatchStdioClient, connectAgentDispatchStdioClient, type AgentDispatchRuntime, type McpToolTransport } from "../src/index.js";
+import {
+  AgentDispatchClient,
+  AgentDispatchMcpClient,
+  AgentDispatchStdioClient,
+  connectAgentDispatchStdioClient,
+  createA2AMessageSendPayload,
+  createCloudAgentA2AHttpRequest,
+  sendCloudAgentA2AMessage,
+  type AgentDispatchRuntime,
+  type McpToolTransport
+} from "../src/index.js";
 
 const request: DispatchRequest = {
   provider: "aws",
@@ -214,3 +224,97 @@ describe("AgentDispatchMcpClient", () => {
     expect(typeof connectAgentDispatchStdioClient).toBe("function");
   });
 });
+
+describe("cloud agent A2A helpers", () => {
+  const cloudAgent = {
+    protocol: "a2a",
+    provider: "aws",
+    backend: "aws-agentcore",
+    accountProfile: "dev-aws",
+    sessionId: "session_123",
+    invocation: {
+      type: "aws.agentcore.invoke_agent_runtime",
+      provider: "aws",
+      accountProfile: "dev-aws",
+      runtimeUrl: "https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/runtime/invocations/",
+      sessionHeaderName: "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id",
+      sessionHeaderValue: "session_123",
+      contentType: "application/json",
+      accept: "application/json"
+    },
+    a2a: {
+      transport: "json-rpc-2.0-http",
+      messageMethod: "message/send",
+      endpointUrl: "https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/runtime/invocations/",
+      sessionHeaderName: "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id",
+      sessionHeaderValue: "session_123"
+    }
+  } as const;
+
+  it("builds A2A message/send payloads", () => {
+    expect(createA2AMessageSendPayload({ id: "req-1", messageId: "msg-1", text: "continue" })).toEqual({
+      jsonrpc: "2.0",
+      id: "req-1",
+      method: "message/send",
+      params: {
+        message: {
+          role: "user",
+          parts: [{ kind: "text", text: "continue" }],
+          messageId: "msg-1"
+        }
+      }
+    });
+  });
+
+  it("builds cloud-agent A2A HTTP requests with AgentCore session headers", () => {
+    const request = createCloudAgentA2AHttpRequest(cloudAgent, {
+      id: "req-1",
+      messageId: "msg-1",
+      text: "continue",
+      metadata: { priority: "background" }
+    });
+
+    expect(request).toMatchObject({
+      url: "https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/runtime/invocations/",
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "application/json",
+        "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": "session_123"
+      }
+    });
+    expect(JSON.parse(request.body)).toMatchObject({
+      jsonrpc: "2.0",
+      method: "message/send",
+      params: {
+        metadata: { priority: "background" },
+        message: { parts: [{ kind: "text", text: "continue" }] }
+      }
+    });
+  });
+
+  it("sends A2A follow-up messages through an injected transport", async () => {
+    const calls: unknown[] = [];
+    const result = await sendCloudAgentA2AMessage(cloudAgent, { text: "next step" }, async (request) => {
+      calls.push(request);
+      return {
+        jsonrpc: "2.0",
+        id: "req-1",
+        result: {
+          kind: "message",
+          role: "agent",
+          parts: [{ kind: "text", text: "done" }],
+          metadata: { ok: true }
+        }
+      };
+    });
+
+    expect(calls).toHaveLength(1);
+    expect(result).toMatchObject({ text: "done", metadata: { ok: true } });
+  });
+
+  it("rejects non-A2A cloud-agent metadata", () => {
+    expect(() => createCloudAgentA2AHttpRequest({ ...cloudAgent, protocol: "http" }, { text: "continue" }))
+      .toThrow("not a2a");
+  });
+});