@aws/nx-plugin 1.0.0-rc.3 → 1.0.0-rc.31

package/src/utils/agent-chat/files/a2a/chat.ts.template

@@ -0,0 +1,33 @@
+// Chat CLI for <%- agentNameClassName %> (A2A protocol). Connects to the local
+// `dev` server, or the deployed agent when `RUNTIME_CONFIG_APP_ID` is set.
+import {
+  ClientFactory,
+  ClientFactoryOptions,
+  DefaultAgentCardResolver,
+  JsonRpcTransportFactory,
+} from '@a2a-js/sdk/client';
+import { A2AChatAdapter, chatLoop } from 'agent-chat-cli';
+import { createAgentCoreFetch, resolveRemoteAgent } from './agentcore.js';
+
+const remote = await resolveRemoteAgent();
+
+const url = remote
+  ? `https://bedrock-agentcore.${remote.region}.amazonaws.com/runtimes/${encodeURIComponent(remote.arn)}/invocations/`
+  : process.env.URL!;
+
+// Remote requests are authenticated via a custom fetch; locally the default client talks plain HTTP.
+const clientFactory = remote
+  ? new ClientFactory({
+      ...ClientFactoryOptions.default,
+      transports: [
+        new JsonRpcTransportFactory({
+          fetchImpl: createAgentCoreFetch(<%- auth === 'iam' ? 'remote.region' : '' %>),
+        }),
+      ],
+      cardResolver: new DefaultAgentCardResolver({
+        fetchImpl: createAgentCoreFetch(<%- auth === 'iam' ? 'remote.region' : '' %>),
+      }),
+    })
+  : undefined;
+
+await chatLoop(new A2AChatAdapter({ clientFactory }), url);

package/src/utils/agent-chat/files/ag-ui/chat.ts.template

@@ -0,0 +1,17 @@
+// Chat CLI for <%- agentNameClassName %> (AG-UI protocol). Connects to the local
+// `dev` server, or the deployed agent when `RUNTIME_CONFIG_APP_ID` is set.
+import { AGUIChatAdapter, chatLoop } from 'agent-chat-cli';
+import { createAgentCoreFetch, resolveRemoteAgent } from './agentcore.js';
+
+const remote = await resolveRemoteAgent();
+
+const url = remote
+  ? `https://bedrock-agentcore.${remote.region}.amazonaws.com/runtimes/${encodeURIComponent(remote.arn)}/invocations?qualifier=DEFAULT`
+  : process.env.URL!;
+
+// Remote requests are authenticated via a custom fetch; locally the default agent talks plain HTTP.
+const fetchImpl = remote
+  ? createAgentCoreFetch(<%- auth === 'iam' ? 'remote.region' : '' %>)
+  : undefined;
+
+await chatLoop(new AGUIChatAdapter({ fetch: fetchImpl }), url);

package/src/utils/agent-chat/files/common/agentcore.ts.template

@@ -0,0 +1,81 @@
+// Resolves the deployed <%- agentNameClassName %> agent from runtime config and authenticates requests to it.
+import { randomUUID } from 'node:crypto';
+import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
+<%_ if (auth === 'iam') { _%>
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+import { AwsClient } from 'aws4fetch';
+<%_ } _%>
+
+const SESSION_HEADER = 'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id';
+
+// AgentCore session ids must be at least 33 characters.
+export const SESSION_ID = randomUUID().replaceAll('-', '').padEnd(33, '0');
+
+export interface RemoteAgent {
+  /** ARN of the deployed Bedrock AgentCore runtime. */
+  arn: string;
+  /** AWS region parsed from the runtime ARN. */
+  region: string;
+}
+
+// Returns the deployed agent when `RUNTIME_CONFIG_APP_ID` is set, otherwise `undefined` to chat locally.
+export const resolveRemoteAgent = async (): Promise<
+  RemoteAgent | undefined
+> => {
+  const application = process.env.RUNTIME_CONFIG_APP_ID;
+  if (!application) {
+    return undefined;
+  }
+  const config = (await getAppConfig('agentcore', {
+    application,
+    environment: 'default',
+    transform: 'json',
+  })) as { agentRuntimes?: Record<string, string> };
+  const arn = config?.agentRuntimes?.['<%- agentNameClassName %>'];
+  if (!arn) {
+    throw new Error(
+      `No deployed agent named '<%- agentNameClassName %>' found in runtime configuration (application ${application}).`,
+    );
+  }
+  return { arn, region: arn.split(':')[3] };
+};
+
+<%_ if (auth === 'cognito') { _%>
+/** The Cognito access token used to authenticate with the deployed agent. */
+export const getAccessToken = (): string => {
+  const accessToken = process.env.AGENT_ACCESS_TOKEN;
+  if (!accessToken) {
+    throw new Error(
+      'AGENT_ACCESS_TOKEN is not set. Provide a Cognito access token to chat with the deployed agent.',
+    );
+  }
+  return accessToken;
+};
+<%_ } _%>
+
+// A `fetch` that authenticates requests to the deployed agent and forwards the session id.
+<%_ if (auth === 'iam') { _%>
+export const createAgentCoreFetch = (region: string): typeof fetch => {
+  const credentialProvider = fromNodeProviderChain();
+  return async (input, init) => {
+    const headers = new Headers(init?.headers);
+    headers.set(SESSION_HEADER, SESSION_ID);
+    const client = new AwsClient({
+      ...(await credentialProvider()),
+      service: 'bedrock-agentcore',
+      region,
+    });
+    return client.fetch(input, { ...init, headers });
+  };
+};
+<%_ } else { _%>
+export const createAgentCoreFetch = (): typeof fetch => {
+  const accessToken = getAccessToken();
+  return (input, init) => {
+    const headers = new Headers(init?.headers);
+    headers.set(SESSION_HEADER, SESSION_ID);
+    headers.set('Authorization', `Bearer ${accessToken}`);
+    return fetch(input, { ...init, headers });
+  };
+};
+<%_ } _%>

package/src/utils/agent-chat/files/http-py/chat.ts.template

@@ -0,0 +1,43 @@
+// Chat CLI for <%- agentNameClassName %> (Python FastAPI / JSONL streaming), using the
+// generated client. Connects to the local `dev` server, or the deployed
+// agent when `RUNTIME_CONFIG_APP_ID` is set.
+import { chatLoop, type ChatAdapter } from 'agent-chat-cli';
+import { <%- agentNameClassName %> } from './generated/client.gen.js';
+import {
+  createAgentCoreFetch,
+  resolveRemoteAgent,
+  SESSION_ID,
+} from './agentcore.js';
+
+const SESSION_ID_HEADER = 'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id';
+
+const remote = await resolveRemoteAgent();
+
+class <%- agentNameClassName %>Adapter implements ChatAdapter {
+  private client!: <%- agentNameClassName %>;
+
+  async connect(url: string) {
+    this.client = remote
+      ? new <%- agentNameClassName %>({
+          url: `https://bedrock-agentcore.${remote.region}.amazonaws.com/runtimes/${encodeURIComponent(remote.arn)}`,
+          fetch: createAgentCoreFetch(<%- auth === 'iam' ? 'remote.region' : '' %>),
+        })
+      : new <%- agentNameClassName %>({
+          url,
+          fetch: (input, init) => {
+            const headers = new Headers(init?.headers);
+            headers.set(SESSION_ID_HEADER, SESSION_ID);
+            return fetch(input, { ...init, headers });
+          },
+        });
+    return { agentName: '<%- agentNameClassName %>' };
+  }
+
+  async *sendMessage(text: string): AsyncIterable<string> {
+    for await (const chunk of this.client.invoke({ message: text })) {
+      if (typeof chunk.content === 'string') yield chunk.content;
+    }
+  }
+}
+
+await chatLoop(new <%- agentNameClassName %>Adapter(), process.env.URL ?? '');

package/src/utils/agent-chat/files/http-ts/chat.ts.template

@@ -0,0 +1,54 @@
+// Chat CLI for <%- agentNameClassName %> (HTTP / tRPC WebSocket). Connects to the local
+// `dev` server, or the deployed agent when `RUNTIME_CONFIG_APP_ID` is set.
+import { chatLoop, type ChatAdapter } from 'agent-chat-cli';
+import { <%- agentNameClassName %>Client } from '<%- relativeAgentImport %>/client.js';
+import {
+  resolveRemoteAgent,
+  SESSION_ID,
+<%_ if (auth === 'cognito') { _%>
+  getAccessToken,
+<%_ } _%>
+} from './agentcore.js';
+
+const remote = await resolveRemoteAgent();
+
+class TrpcWebSocketAdapter implements ChatAdapter {
+  private client!: ReturnType<typeof <%- agentNameClassName %>Client.local>;
+
+  async connect(url: string) {
+    this.client = remote
+<%_ if (auth === 'iam') { _%>
+      ? <%- agentNameClassName %>Client.withIamAuth({
+          agentRuntimeArn: remote.arn,
+          sessionId: SESSION_ID,
+        })
+<%_ } else { _%>
+      ? <%- agentNameClassName %>Client.withJwtAuth({
+          agentRuntimeArn: remote.arn,
+          sessionId: SESSION_ID,
+          accessTokenProvider: async () => getAccessToken(),
+        })
+<%_ } _%>
+      : <%- agentNameClassName %>Client.local({ url, sessionId: SESSION_ID });
+    return { agentName: '<%- agentNameClassName %>' };
+  }
+
+  async *sendMessage(text: string): AsyncIterable<string> {
+    const stream = new ReadableStream<string>({
+      start: (controller) => {
+        this.client.invoke.subscribe(
+          { message: text },
+          {
+            onData: (chunk: string) => controller.enqueue(chunk),
+            onComplete: () => controller.close(),
+            onError: (err: unknown) => controller.error(err),
+          },
+        );
+      },
+    });
+
+    yield* stream as unknown as AsyncIterable<string>;
+  }
+}
+
+await chatLoop(new TrpcWebSocketAdapter(), process.env.URL ?? '');

package/src/utils/agent-connection/agent-connection.d.ts

@@ -2,7 +2,8 @@
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
-import { Tree } from '@nx/devkit';
+import { type Tree } from '@nx/devkit';
+import type { IPyDepVersion } from '../versions';
 export declare const AGENT_CONNECTION_PROJECT_DIR: string;
 /**
  * Get the directory of the shared Python agent-connection project.
@@ -13,36 +14,62 @@ export declare function getPythonAgentConnectionProjectDir(tree: Tree): string;
  */
 export declare function getPythonAgentConnectionModuleName(tree: Tree): string;
 /**
- * Get the fully qualified Python package name of the shared agent-connection project.
+ * Get the shared agent-connection project as `{ name, root }`, suitable for
+ * passing to {@link addWorkspaceDependencyToPyProject} (which derives the
+ * dependency's PEP 503 distribution name from the project itself, so callers
+ * never construct the name).
  */
-export declare function getPythonAgentConnectionPackageName(tree: Tree): string;
+export declare function getPythonAgentConnectionProject(tree: Tree): {
+    name: string;
+    root: string;
+};
 /**
- * Directories (relative to this file) holding per-protocol core client
- * template files. Per-connection generators select which set to emit so
- * the MCP connection doesn't pull in the A2A client (or vice versa).
+ * The connection protocols an agent framework can connect over. Each maps to a
+ * framework-agnostic Layer-0/1 template directory plus a per-framework Layer-2
+ * client directory (see `FRAMEWORKS`).
  */
-export declare const TS_CORE_TEMPLATES: {
-    readonly mcp: "core-mcp";
-    readonly a2a: "core-a2a";
-};
-export declare const PY_CORE_TEMPLATES: {
-    readonly mcp: "py-core-mcp";
-    readonly a2a: "py-core-a2a";
-    /** Shared SigV4 `httpx.Auth` used by both MCP and A2A clients. */
-    readonly auth: "py-core-auth";
-};
+export type ConnectionProtocol = 'mcp' | 'gateway' | 'a2a';
+/**
+ * The agent frameworks we can generate connection clients for. Adding a new
+ * framework is an additive change: append an entry to `FRAMEWORKS` with its
+ * Layer-2 template directories and dependencies — the framework-agnostic
+ * Layer-0/1 (`core-auth`, `core-shared`, the per-protocol transports/configs)
+ * is reused unchanged.
+ */
+export type AgentFramework = 'strands' | 'langchain';
+/**
+ * Resolve an agent component's framework, defaulting to `strands`. Connection
+ * generators dispatch on the returned framework to pick the matching templates
+ * and agent.py/agent.ts transforms.
+ */
+export declare function resolveAgentFramework(framework: string | undefined): AgentFramework;
 /**
  * Ensure the shared TypeScript agent-connection project exists and has the
- * shared core helpers (runtime-config loader). Per-connection generators
- * are responsible for emitting their own per-protocol core client templates.
+ * framework-agnostic core helpers (runtime-config loader, session context).
+ * Per-connection generators emit their own protocol + framework client
+ * templates via `addTypeScriptCoreClient`.
  */
 export declare function ensureTypeScriptAgentConnectionProject(tree: Tree): Promise<void>;
 /**
- * Emit one of the TypeScript core client templates (mcp or a2a) into the
- * agent-connection project's `src/core/` directory. Safe to call multiple
- * times — `KeepExisting` preserves customised files.
+ * Emit a framework's base Layer-2 helpers (model-error logging + per-session
+ * agent cache) into the agent-connection project and re-export them. The agent
+ * server entry point imports these regardless of whether any connection client
+ * is wired in, so the agent generator calls this directly; connection
+ * generators call it transitively via `addTypeScriptCoreClient`.
+ */
+export declare function addTypeScriptFrameworkBase(tree: Tree, framework?: AgentFramework): Promise<void>;
+/**
+ * Emit the TypeScript client templates for a connection protocol and agent
+ * framework into the agent-connection project's `src/core/` directory. Safe to
+ * call multiple times — `KeepExisting` preserves customised files.
+ *
+ * Layers emitted:
+ *  - Layer 0 `core-auth` (signed fetch + endpoint resolution) — always
+ *  - Layer 1 `core-shared` MCP transport — for mcp/gateway protocols
+ *  - Layer 1 the protocol's transport/client-config — always
+ *  - Layer 2 the framework's base helpers + protocol client — per framework
  */
-export declare function addTypeScriptCoreClient(tree: Tree, kind: keyof typeof TS_CORE_TEMPLATES): void;
+export declare function addTypeScriptCoreClient(tree: Tree, protocol: ConnectionProtocol, framework?: AgentFramework): Promise<void>;
 /**
  * Ensure the shared Python agent-connection project exists.
  * Only creates the project shell — per-connection generators are responsible
@@ -50,10 +77,75 @@ export declare function addTypeScriptCoreClient(tree: Tree, kind: keyof typeof T
  */
 export declare function ensurePythonAgentConnectionProject(tree: Tree): Promise<void>;
 /**
- * Emit a Python core client template (mcp / a2a / shared auth) into the
- * agent-connection project's core directory.
+ * Emit a framework's base Layer-2 helpers (model-error logging + per-session
+ * agent cache) into the Python agent-connection project and re-export them.
+ * The agent server entry point imports these regardless of whether a connection
+ * client is wired in, so the agent generator calls this directly; connection
+ * generators call it transitively via `addPythonCoreClient`.
+ */
+export declare function addPythonFrameworkBase(tree: Tree, framework?: AgentFramework): Promise<void>;
+/**
+ * Emit the Python client templates for a connection protocol and agent
+ * framework into the agent-connection project's core directory.
+ *
+ * Layers emitted:
+ *  - Layer 0 `py-core-auth` (SigV4 httpx.Auth, session auth, endpoints) — always
+ *  - Layer 1 `py-core-shared` MCP transport — for mcp/gateway protocols
+ *  - Layer 1 the protocol's transport/client-config — always
+ *  - Layer 2 the framework's base helpers + protocol client — per framework
+ */
+export declare function addPythonCoreClient(tree: Tree, protocol: ConnectionProtocol, framework?: AgentFramework): Promise<void>;
+/**
+ * Patch a TypeScript agent.ts to create a connection client and register it
+ * in the Agent's tools. Used by the MCP and gateway connection generators —
+ * the client class must expose a static async `create()` returning a value
+ * accepted by `Agent.tools` (e.g. an `McpClient`).
+ */
+export declare function addTypeScriptClientToAgent(tree: Tree, agentFilePath: string, clientClassName: string, clientVarName: string): Promise<void>;
+/**
+ * Per-framework naming + template layout for a Python per-connection client.
+ * Every py#agent connection generator (mcp, gateway, a2a) names its client
+ * class `<Name>Client<suffix>`, its module `<name>_client_<suffix>`, and reads
+ * the per-connection app-client template from a per-framework sub-path of its
+ * own `files/` dir — all of which vary only by framework, so they live here as
+ * one source of truth.
+ *
+ * Keyed by {@link AgentFramework} rather than a boolean so a third framework is
+ * an additive entry here — never another `if (isLangchain)` branch in each
+ * generator.
+ */
+export interface PyClientNaming {
+    /** Class-name suffix on the per-connection app client (`<Name>Client<suffix>`). */
+    clientClassSuffix: string;
+    /** Module/file-name suffix on the per-connection app client (`<name>_client_<suffix>`). */
+    clientModuleSuffix: string;
+    /**
+     * Sub-path, under a connection generator's `files/` dir, of the per-connection
+     * app client template for this framework. Every connection generator lays its
+     * templates out the same way, so this resolves against any of them.
+     */
+    appTemplateSubdir: string;
+}
+export declare const PY_CLIENT_NAMING: Record<AgentFramework, PyClientNaming>;
+/**
+ * How an MCP-family connection (an MCP server or an AgentCore Gateway, both of
+ * which expose tools over MCP) is wired into a Python agent of a given
+ * framework. The mcp-connection and gateway-connection generators share this:
+ * they differ only in the metadata of the thing being connected, not in how
+ * the framework's client is shaped or spliced into agent.py. A2A connections
+ * wire tools differently, so they reuse only {@link PY_CLIENT_NAMING}.
  */
-export declare function addPythonCoreClient(tree: Tree, kind: keyof typeof PY_CORE_TEMPLATES): void;
+export interface PyMcpFamilyConnection extends PyClientNaming {
+    /** Extra Python deps this framework's MCP-family client needs (beyond the shared transport). */
+    deps: IPyDepVersion[];
+    /**
+     * Splice the per-connection client into the agent's `get_agent` in agent.py.
+     * Strands enters a context-managed `MCPClient` and spreads `list_tools_sync()`;
+     * LangChain loads `BaseTool`s and spreads them into `create_agent(...)`.
+     */
+    wireClientIntoAgent: (tree: Tree, agentFilePath: string, clientClassName: string, clientVarName: string) => Promise<void>;
+}
+export declare const PY_MCP_FAMILY_CONNECTIONS: Record<AgentFramework, PyMcpFamilyConnection>;
 /**
  * Add a re-export to the Python agent-connection module's __init__.py.
  * Equivalent to addStarExport for TS.