Skip to content
@aws/nx-plugin
Blog

Python Agent

Filter this guide Pick generator option values to hide sections that don't apply.

Generate a Python AI agent for building agents with tools, and optionally deploy it to Amazon Bedrock AgentCore Runtime. Choose the agent framework with the framework option: Strands (the default) or LangChain (built on LangGraph).

The generator exposes your agent over a server protocol. Both frameworks support HTTP (the default), the Agent-to-Agent (A2A) protocol for interoperability with other A2A-compatible agents, and the AG-UI protocol for direct frontend integration via CopilotKit.

Usage

Section titled “Usage”

Generate an Agent

Section titled “Generate an Agent”

You can generate a Python Agent in two ways:

  1. Install the Nx Console VSCode Plugin if you haven't already
  2. Open the Nx Console in VSCode
  3. Click Generate (UI) in the "Common Nx Commands" section
  4. Search for @aws/nx-plugin - py#agent
  5. Fill in the required parameters
    • Click Generate

    Options

    Section titled “Options”
    Parameter Type Default Description
    project Required string - The project to add the Agent to
    framework strands | langchain strands The agent SDK to use.
    name string - The name of your Agent (default: agent)
    auth iam | cognito iam The method used to authenticate with your Agent. Only applicable when infra is set (ignored when infra is none).
    protocol http | a2a | ag-ui http The server protocol for your Agent. HTTP exposes a FastAPI HTTP server. A2A exposes an Agent-to-Agent protocol server. AG-UI exposes an Agent-User Interaction protocol server for direct frontend integration.
    iac inherit | cdk | terraform inherit The preferred IaC provider. By default this is inherited from your initial selection.
    infra agentcore | none agentcore The type of infrastructure to host your Agent.
    preferInstallDependencies boolean true Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

    Generator Output

    Section titled “Generator Output”

    The generator will add the following files to your existing Python project. The files generated depend on the chosen protocol:

    protocol = http

    HTTP Protocol (default)

    Section titled “HTTP Protocol (default)”
    • Directoryyour-project/
      • Directoryyour_module/
        • Directoryagent/ (or custom name if specified)
          • __init__.py Python package initialization
          • init.py FastAPI application setup with CORS and error handling middleware
          • agent.py Main agent definition with sample tools
          • main.py FastAPI entry point for Bedrock AgentCore Runtime
          • Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
      • pyproject.toml Updated with Strands dependencies
      • project.json Updated with agent serve targets
    protocol = a2a

    A2A Protocol

    Section titled “A2A Protocol”

    The entry point exposes your agent over the A2A protocol (Strands uses the Strands A2A Server; LangChain wraps the graph in an a2a-sdk executor), mounted onto a FastAPI app:

    • Directoryyour-project/
      • Directoryyour_module/
        • Directoryagent/ (or custom name if specified)
          • __init__.py Python package initialization
          • agent.py Main agent definition with sample tools
          • main.py A2A server entry point
          • Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
      • pyproject.toml Updated with framework and A2A dependencies
      • project.json Updated with agent serve targets
    protocol = ag-ui

    AG-UI Protocol

    Section titled “AG-UI Protocol”

    The entry point exposes your agent via the AG-UI protocol for direct frontend integration with CopilotKit. Strands agents use the ag-ui-strands integration; LangChain agents use ag-ui-langgraph:

    • Directoryyour-project/
      • Directoryyour_module/
        • Directoryagent/ (or custom name if specified)
          • __init__.py Python package initialization
          • agent.py Main agent definition with sample tools
          • main.py AG-UI server entry point
          • Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
      • pyproject.toml Updated with framework and AG-UI dependencies
      • project.json Updated with agent serve targets

    Infrastructure

    Section titled “Infrastructure”
    infra = agentcore

    Since this generator vends infrastructure as code based on your chosen iacProvider, it will create a project in packages/common which includes the relevant CDK constructs or Terraform modules.

    The common infrastructure as code project is structured as follows:

    • Directorypackages/common/constructs
      • Directorysrc
        • Directoryapp/ Constructs for infrastructure specific to a project/generator
          • …
        • Directorycore/ Generic constructs which are reused by constructs in app
          • …
        • index.ts Entry point exporting constructs from app
      • project.json Project build targets and configuration

    For deploying your Agent, the following files are generated:

    • Directorypackages/common/constructs/src
      • Directoryapp
        • Directoryagents
          • Directory<project-name>
            • <project-name>.ts CDK construct for deploying your agent
    infra = none

    If you selected none for infra, no CDK constructs or Terraform modules are generated — the Agent can only be run locally. The auth option is ignored in this mode since there is no hosted endpoint to authenticate.

    Architecture

    Section titled “Architecture”

    When deployed to Bedrock AgentCore Runtime, the agent is built into a container image, pushed to Amazon ECR and run in AgentCore Runtime. Clients invoke the AgentCore Runtime data plane endpoint, which forwards requests to your agent. The agent calls Amazon Bedrock for model inference and may invoke tools, MCP servers, or downstream APIs.

    ClientECRStrands Agent(AgentCore Runtime)Bedrock(Model Inference)CloudWatch(Logs, Metrics) Containerimage InvokeModel

    Working with Your Agent

    Section titled “Working with Your Agent”

    You can edit agent.py to add tools, configure the model and customize the system prompt. The API depends on the framework you chose.

    Adding Tools

    Section titled “Adding Tools”

    Tools are functions that the AI agent can call to perform actions. Both frameworks use a decorator-based approach for defining tools, derive the tool name and description from the function name and docstring, and generate the input schema from your type hints.

    from strands import Agent, tool
    

    @tool
    def calculate_sum(numbers: list[int]) -> int:
        """Calculate the sum of a list of numbers"""
        return sum(numbers)
    

    @tool
    def get_weather(city: str) -> str:
        """Get weather information for a city"""
        # Your weather API integration here
        return f"Weather in {city}: Sunny, 25°C"
    

    # Add tools to your agent
    agent = Agent(
        system_prompt="You are a helpful assistant with access to various tools.",
        tools=[calculate_sum, get_weather],
    )

    Using Pre-built Tools

    Section titled “Using Pre-built Tools”

    Strands provides a collection of pre-built tools through the strands-tools package:

    from strands_tools import current_time, http_request, file_read
    

    agent = Agent(
        system_prompt="You are a helpful assistant.",
        tools=[current_time, http_request, file_read],
    )

    Model Configuration

    Section titled “Model Configuration”

    By default, Strands agents use Claude 4 Sonnet, but you can customize the model provider. See the Strands documentation on model providers for configuration options:

    from strands import Agent
    from strands.models import BedrockModel
    

    # Create a BedrockModel
    bedrock_model = BedrockModel(
        model_id="anthropic.claude-sonnet-4-20250514-v1:0",
        region_name="us-west-2",
        temperature=0.3,
    )
    

    agent = Agent(model=bedrock_model)

    Consuming MCP Servers

    Section titled “Consuming MCP Servers”

    For consuming MCP Servers which you have created using the py#mcp-server or ts#mcp-server generators you can make use of the connection generator, which wires the MCP server’s tools into your agent for both frameworks.

    1. Install the Nx Console VSCode Plugin if you haven't already
    2. Open the Nx Console in VSCode
    3. Click Generate (UI) in the "Common Nx Commands" section
    4. Search for @aws/nx-plugin - connection
    5. Fill in the required parameters
      • Click Generate

      Refer to the connection generator guide for details about how the connection is set up.

      For other MCP servers, refer to the Strands or LangChain MCP documentation.

      More

      Section titled “More”

      For a more in-depth guide to writing agents, refer to the Strands or LangChain documentation.

      Protocol

      Section titled “Protocol”

      Your agent’s server protocol determines how it communicates. All options are served by FastAPI — the entry point differs:

      • HTTP (default): A standard FastAPI server with a custom /invocations endpoint, CORS, and streaming. Best for custom client integrations.
      • A2A: An Agent-to-Agent server mounted onto a FastAPI app (Strands uses the Strands A2A Server; LangChain uses the framework-agnostic a2a-sdk). Best when your agent needs to be discoverable and invokable by other A2A-compatible agents.
      • AG-UI: The AG-UI protocol over SSE (Strands uses ag-ui-strands; LangChain uses ag-ui-langgraph). Best for direct frontend integration with CopilotKit in a React website.

      The server entry point differs by framework (Strands yields a context-managed Agent, while LangChain drives a compiled create_agent graph), but the external contract for each protocol is the same.

      All protocols expose /ping for the AgentCore runtime health check contract. A2A agents listen on port 9000; HTTP and AG-UI agents listen on port 8080. The generated Dockerfile and infrastructure are configured for you.

      protocol = http

      FastAPI Server (HTTP protocol)

      Section titled “FastAPI Server (HTTP protocol)”

      The generated HTTP server includes:

      • FastAPI application setup with CORS middleware
      • Error handling middleware
      • OpenAPI schema generation
      • Health check endpoint (/ping)
      • Agent invocation endpoint (/invocations)

      Customizing Invoke Inputs and Outputs with Pydantic

      Section titled “Customizing Invoke Inputs and Outputs with Pydantic”

      The agent’s invocation endpoint uses Pydantic models to define and validate the request and response schemas. You can customize these models in main.py to match your agent’s requirements.

      Defining Input Models

      Section titled “Defining Input Models”

      The default InvokeInput model accepts a message.

      from pydantic import BaseModel
      

      class InvokeInput(BaseModel):
          message: str

      You can extend this model to include any additional fields your agent needs.

      The session ID is extracted from the x-amzn-bedrock-agentcore-runtime-session-id HTTP header, consistent with the Bedrock AgentCore Runtime session contract. If the header is not provided, a random UUID is generated as a fallback.

      Defining Output Models

      Section titled “Defining Output Models”

      For streaming responses, the generator provides JsonStreamingResponse which automatically serializes Pydantic models to JSON Lines format (application/jsonl). This format is compatible with OpenAPI 3.2’s streaming specification and works seamlessly with the generated TypeScript client.

      By default, the agent yields StreamChunk objects containing the agent’s response text:

      class StreamChunk(BaseModel):
          content: str

      You can customise the StreamChunk model to suit your needs:

      from pydantic import BaseModel
      

      class StreamChunk(BaseModel):
          content: str
          timestamp: str
          token_count: int

      There is an open feature request for native support in FastAPI.

      Bedrock AgentCore Python SDK

      Section titled “Bedrock AgentCore Python SDK”

      The generator includes a dependency on the Bedrock AgentCore Python SDK for the PingStatus constants. If desired, it is straightforward to use BedrockAgentCoreApp instead of FastAPI, however note that type-safety is lost.

      You can find more details about the SDK’s capabilities in the documentation here.

      protocol = a2a

      A2A Server (A2A protocol)

      Section titled “A2A Server (A2A protocol)”

      The generated main.py mounts an A2A server onto a parent FastAPI app that also exposes /ping. Strands agents use the Strands A2AServer; LangChain agents wrap the compiled graph in an a2a-sdk AgentExecutor. When deployed to AgentCore, the entry point resolves the runtime’s public ARN from AppConfig and advertises it in the agent card.

      Most users will not need to modify this file; edit agent.py to change tools or the system prompt. The A2A server populates the agent card (/.well-known/agent-card.json) from the agent’s name and description.

      protocol = ag-ui

      AG-UI Server (AG-UI protocol)

      Section titled “AG-UI Server (AG-UI protocol)”

      The generated main.py exposes a single POST endpoint that streams AG-UI events over Server-Sent Events (SSE), as well as /ping for the AgentCore runtime health check. The wiring depends on the framework:

      • Strands: wraps your Agent in an ag_ui_strands.StrandsAgent and creates the FastAPI app via create_strands_app().
      • LangChain: wraps the compiled graph in an ag_ui_langgraph.LangGraphAgent and serves it from a hand-rolled FastAPI /invocations loop.

      Most users will not need to modify this file — edit agent.py to change tools or the system prompt.

      Running Your Agent

      Section titled “Running Your Agent”

      Local Development

      Section titled “Local Development”

      To run your Agent (and everything connected to it) locally, use the project’s dev target:

      Terminal window
      pnpm nx dev your-project

      If you have added multiple components to your project (agents, MCP servers, etc.), this starts them all. To run just this agent, target its <your-agent-name>-dev target:

      Terminal window
      pnpm nx agent-dev your-project

      This uses uv run to execute your Agent using the Bedrock AgentCore Python SDK.

      Chat with Your Agent

      Section titled “Chat with Your Agent”

      The generator configures a <your-agent-name>-chat Nx target that drops you into an interactive terminal chat with your agent.

      The chat target runs standalone. By default it connects to your locally running agent, so start the agent’s <your-agent-name>-dev target first (in a separate terminal):

      Terminal window
      pnpm nx agent-dev your-project

      Then, in another terminal, start the chat:

      Terminal window
      pnpm nx run your-project:agent-chat

      The generator emits a scripts/<your-agent-name>/chat.ts for every protocol. It connects to the local agent by default, or to your deployed agent when RUNTIME_CONFIG_APP_ID is set (see Chat with your deployed agent below).

      For HTTP agents, the chat script uses a type-safe TypeScript client generated from the agent’s OpenAPI spec. The generator also emits:

      • scripts/<your-agent-name>_openapi.py — a small script that exports the agent’s OpenAPI spec
      • An <your-agent-name>-openapi Nx target that runs it
      • An <your-agent-name>-generate-client Nx target that produces a type-safe TypeScript client under scripts/<your-agent-name>/generated/

      When you customize the agent’s input shape (e.g. add new fields to InvokeInput), update chat.ts to pass the new fields when invoking the agent and the rest works automatically.

      infra = agentcore

      Chat with your deployed agent

      Section titled “Chat with your deployed agent”

      To chat with your agent deployed to Bedrock AgentCore, set the RUNTIME_CONFIG_APP_ID environment variable to the AppConfig application id of the deployment (output as RuntimeConfigApplicationId by the deployed stack). The chat script resolves your agent’s runtime ARN from runtime configuration and connects to the deployed endpoint:

      For IAM-authenticated agents, requests are signed with SigV4 using your default AWS credentials. Ensure the environment has AWS credentials with permission to invoke the runtime:

      Terminal window
      RUNTIME_CONFIG_APP_ID=<app-id> pnpm nx run your-project:agent-chat
      infra = agentcore

      Deploying Your Agent to Bedrock AgentCore Runtime

      Section titled “Deploying Your Agent to Bedrock AgentCore Runtime”

      Infrastructure as Code

      Section titled “Infrastructure as Code”

      If you selected agentcore for infra, the relevant CDK or Terraform infrastructure is generated which you can use to deploy your Agent to Amazon Bedrock AgentCore Runtime.

      A CDK construct is generated for your agent, named based on the name you chose when running the generator, or <ProjectName>Agent by default.

      You can use this CDK construct in a CDK application:

      import { MyProjectAgent } from ':my-scope/common-constructs';
      

      export class ExampleStack extends Stack {
        constructor(scope: Construct, id: string) {
          new MyProjectAgent(this, 'MyProjectAgent');
        }
      }

      Authentication

      Section titled “Authentication”

      The generator provides an auth option to configure authentication for your Agent. You can choose between IAM (default) or Cognito authentication when generating your agent.

      IAM

      Section titled “IAM”

      By default, your Agent will be secured using IAM authentication, simply deploy it without any arguments:

      import { MyProjectAgent } from ':my-scope/common-constructs';
      

      export class ExampleStack extends Stack {
        constructor(scope: Construct, id: string) {
          new MyProjectAgent(this, 'MyProjectAgent');
        }
      }

      You can grant access to invoke your agent on Bedrock AgentCore Runtime using the grantInvokeAccess method, for example:

      import { MyProjectAgent } from ':my-scope/common-constructs';
      

      export class ExampleStack extends Stack {
        constructor(scope: Construct, id: string) {
          const agent = new MyProjectAgent(this, 'MyProjectAgent');
          const lambdaFunction = new Function(this, ...);
      

          agent.grantInvokeAccess(lambdaFunction);
        }
      }

      Cognito Authentication

      Section titled “Cognito Authentication”

      When you select Cognito authentication, the generator configures the agent to use Cognito for authentication.

      The generated construct accepts an identity prop which configures Cognito authentication:

      import { MyProjectAgent, UserIdentity } from ':my-scope/common-constructs';
      

      export class ExampleStack extends Stack {
        constructor(scope: Construct, id: string) {
          const identity = new UserIdentity(this, 'Identity');
      

          new MyProjectAgent(this, 'MyProjectAgent', {
            identity,
          });
        }
      }

      The UserIdentity construct can be generated using the ts#website#auth generator, or you can create your own CDK UserPool and UserPoolClient.

      Bundle and Docker Targets

      Section titled “Bundle and Docker Targets”

      In order to build your Agent for Bedrock AgentCore Runtime, a bundle target is added to your project, which:

      • Exports your Python dependencies to a requirements.txt file using uv export
      • Installs dependencies for the target platform (aarch64-manylinux_2_28) using uv pip install

      A docker target specific to your Agent is also added, which copies the Dockerfile and bundled artifacts into a docker context directory. This co-locates the Dockerfile with the built output, allowing CDK to build the Docker image directly using AgentRuntimeArtifact.fromAsset.

      Observability

      Section titled “Observability”

      Your agent is automatically configured with observability using the AWS Distro for Open Telemetry (ADOT), by configuring auto-instrumentation in your Dockerfile.

      You can find traces in the CloudWatch AWS Console, by selecting “GenAI Observability” in the menu. Note that for traces to be populated you will need to enable Transaction Search.

      For more details, refer to the AgentCore documentation on observability.

      Invoking your Agent

      Section titled “Invoking your Agent”
      protocol = http

      Invoke the Local Server

      Section titled “Invoke the Local Server”

      To invoke an Agent running locally via the <your-agent-name>-serve target, you can send a simple POST request to /invocations on the port your local agent is running on. For example, with curl:

      Terminal window
      curl -N -X POST http://localhost:8081/invocations \
        -d '{"message": "what is 3 + 5?"}' \
        -H "Content-Type: application/json"

      Invoke the Deployed Agent

      Section titled “Invoke the Deployed Agent”

      To invoke your Agent deployed to Bedrock AgentCore Runtime, you can send a POST request to the Bedrock AgentCore Runtime dataplane endpoint with your URL-encoded runtime ARN.

      You can obtain the runtime ARN from your infrastructure as follows:

      import { CfnOutput } from 'aws-cdk-lib';
      import { MyProjectAgent } from ':my-scope/common-constructs';
      

      export class ExampleStack extends Stack {
        constructor(scope: Construct, id: string) {
          const agent = new MyProjectAgent(this, 'MyProjectAgent');
      

          new CfnOutput(this, 'AgentArn', {
            value: agent.agentCoreRuntime.agentRuntimeArn,
          });
        }
      }

      The ARN will have the following format: arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>.

      You can then URL-encode the ARN by replacing : with %3A and / with %2F.

      The Bedrock AgentCore Runtime dataplane URL for invoking the agent is as follows:

      https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations

      The exact way to invoke this URL depends upon the authentication method used.

      IAM Authentication

      Section titled “IAM Authentication”

      For IAM Authentication, the request must be signed using AWS Signature Version 4 (SigV4).

      Terminal window
      acurl <region> bedrock-agentcore -N -X POST \
      'https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
      -d '{"message": "what is 3 + 5?"}' \
      -H 'Content-Type: application/json'
      Click here for more details on configuring the above acurl command

      Browser / React Website

      Section titled “Browser / React Website”

      For invoking your Agent from a React website, you can make use of the connection generator, which automatically sets up a client with the correct authentication (IAM or Cognito).

      1. Install the Nx Console VSCode Plugin if you haven't already
      2. Open the Nx Console in VSCode
      3. Click Generate (UI) in the "Common Nx Commands" section
      4. Search for @aws/nx-plugin - connection
      5. Fill in the required parameters
        • Click Generate

        Refer to the connection generator guide for details about how the connection is set up.

        protocol = a2a

        Invoking an A2A Agent as a Tool

        Section titled “Invoking an A2A Agent as a Tool”

        To delegate work from this agent to a remote A2A agent (either TypeScript or Python), use the connection generator. It vends a SigV4-authenticated client for the target agent and AST-transforms this agent’s agent.py to register the remote A2A agent as a @tool-decorated delegate.

        1. Install the Nx Console VSCode Plugin if you haven't already
        2. Open the Nx Console in VSCode
        3. Click Generate (UI) in the "Common Nx Commands" section
        4. Search for @aws/nx-plugin - connection
        5. Fill in the required parameters
          • Click Generate

          Refer to the connection generator guide for details about how the connection is set up.

          protocol = ag-ui

          Invoking an AG-UI Agent

          Section titled “Invoking an AG-UI Agent”

          To invoke your AG-UI agent from a React website, use the connection generator, which wires up a CopilotKit client configured for your deployed agent with the correct authentication (IAM or Cognito).

          1. Install the Nx Console VSCode Plugin if you haven't already
          2. Open the Nx Console in VSCode
          3. Click Generate (UI) in the "Common Nx Commands" section
          4. Search for @aws/nx-plugin - connection
          5. Fill in the required parameters
            • Click Generate

            Refer to the connection generator guide for details about how the connection is set up.

            Connections

            Section titled “Connections”

            Use the connection generator to integrate this project with others in your workspace. The following connections involve this project:

            Strands Agents Python
            React to Python Agent Call a Python Agent from a React website
            CopilotKit
            React to AG-UI Agent Call an Agent exposing the AG-UI protocol from a React website via CopilotKit
            Strands Agents Python Model Context Protocol
            Python Agent to MCP Connect a Python Agent to an MCP server
            Strands Agents Python Agent2Agent
            Python Agent to A2A Agent Connect a Python Agent to a remote A2A agent
            Strands Agents TypeScript Agent2Agent
            TypeScript Agent to A2A Agent Connect a TypeScript Agent to a remote A2A agent
            Strands Agents Python Amazon DynamoDB Python
            Python Agent to Python DynamoDB Connect a Python Agent to a DynamoDB table
            Strands Agents Python Amazon Bedrock AgentCore Gateway
            Python Agent to AgentCore Gateway Connect a Python Agent to an AgentCore Gateway