Agente de Strands em Python

Gere um Agente Strands em Python para construir agentes de IA com ferramentas, e opcionalmente implante-o no Amazon Bedrock AgentCore Runtime. Por padrão, o gerador usa FastAPI para expor um servidor HTTP. Alternativamente, você pode escolher o protocolo Agent-to-Agent (A2A) para interoperabilidade com outros agentes compatíveis com A2A, ou o protocolo AG-UI para integração direta com frontend via CopilotKit.

O que é o Strands?

Strands é um framework Python leve e pronto para produção para construção de agentes de IA. Principais recursos incluem:

• Leve e personalizável: Loop de agente simples que não atrapalha
• Pronto para produção: Observabilidade completa, tracing e opções de implantação para escala
• Agnóstico de modelo e provedor: Suporte a diversos modelos de vários provedores
• Ferramentas comunitárias: Conjunto poderoso de ferramentas contribuídas pela comunidade
• Suporte a multiagentes: Técnicas avançadas como equipes de agentes e agentes autônomos
• Modos de interação flexíveis: Suporte a conversacional, streaming e não-streaming

Uso

Gerar um Agente Strands

Você pode gerar um Agente Strands em Python de duas formas:

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - py#strands-agent
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:py#strands-agent

yarn

yarn nx g @aws/nx-plugin:py#strands-agent

npm

npx nx g @aws/nx-plugin:py#strands-agent

bun

bunx nx g @aws/nx-plugin:py#strands-agent

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

pnpm

pnpm nx g @aws/nx-plugin:py#strands-agent --dry-run

yarn

yarn nx g @aws/nx-plugin:py#strands-agent --dry-run

npm

npx nx g @aws/nx-plugin:py#strands-agent --dry-run

bun

bunx nx g @aws/nx-plugin:py#strands-agent --dry-run

Pré-requisito do projeto

Primeiro use o gerador py#project para criar um projeto onde adicionar seu Agente Strands.

Opções

Parâmetro	Tipo	Padrão	Descrição
project Obrigatório	string	-	O projeto ao qual adicionar o Strands Agent
computeType	string	BedrockAgentCoreRuntime	O tipo de computação para hospedar seu Strands Agent.
name	string	-	O nome do seu Strands Agent (padrão: agent)
auth	string	IAM	O método usado para autenticar com seu Strands Agent. Escolha entre IAM (padrão) ou Cognito.
protocol	string	HTTP	O protocolo do servidor para o seu Strands Agent. HTTP expõe um servidor HTTP FastAPI. A2A expõe um servidor de protocolo Agent-to-Agent. AG-UI expõe um servidor de protocolo Agent-User Interaction para integração direta com frontend.
iacProvider	string	Inherit	O provedor de IaC preferido. Por padrão, isso é herdado da sua seleção inicial.

Saída do Gerador

O gerador adicionará os seguintes arquivos ao seu projeto Python existente. Os arquivos gerados dependem do protocol escolhido:

protocol = HTTP

Protocolo HTTP (padrão)

• Directoryyour-project/

  • Directoryyour_module/

    • Directoryagent/ (ou nome personalizado se especificado)

      • __init__.py Inicialização do pacote Python
      • init.py Configuração da aplicação FastAPI com middleware CORS e tratamento de erros
      • agent.py Definição principal do agente com ferramentas de exemplo
      • main.py Ponto de entrada FastAPI para Bedrock AgentCore Runtime
      • Dockerfile Ponto de entrada para hospedar seu agente (excluído quando computeType é None)
  • pyproject.toml Atualizado com dependências do Strands
  • project.json Atualizado com alvos de serviço do agente

protocol = A2A

Protocolo A2A

O ponto de entrada usa o Strands A2A Server em vez do FastAPI:

• Directoryyour-project/

  • Directoryyour_module/

    • Directoryagent/ (ou nome personalizado se especificado)

      • __init__.py Inicialização do pacote Python
      • agent.py Definição principal do agente com ferramentas de exemplo
      • main.py Ponto de entrada do servidor A2A
      • Dockerfile Ponto de entrada para hospedar seu agente (excluído quando computeType é None)
  • pyproject.toml Atualizado com dependências do Strands
  • project.json Atualizado com alvos de serviço do agente

protocol = AG-UI

Protocolo AG-UI

O ponto de entrada usa a integração ag-ui-strands, que expõe seu agente via protocolo AG-UI para integração direta com frontend usando CopilotKit:

• Directoryyour-project/

  • Directoryyour_module/

    • Directoryagent/ (ou nome personalizado se especificado)

      • __init__.py Inicialização do pacote Python
      • agent.py Definição principal do agente com ferramentas de exemplo
      • main.py Ponto de entrada do servidor AG-UI usando ag-ui-strands
      • Dockerfile Ponto de entrada para hospedar seu agente (excluído quando computeType é None)
  • pyproject.toml Atualizado com dependências do Strands e AG-UI
  • project.json Atualizado com alvos de serviço do agente

Conectar a um website React

Agentes AG-UI podem ser conectados a um frontend React usando o gerador connection, que configurará componentes do CopilotKit para uma experiência de chat rica.

Infraestrutura

computeType = BedrockAgentCoreRuntime

Como este gerador fornece infraestrutura como código com base no iacProvider escolhido, ele criará um projeto em packages/common que inclui os constructs CDK ou módulos Terraform relevantes.

O projeto comum de infraestrutura como código está estruturado da seguinte forma:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructs para infraestrutura específica de um projeto/gerador

      • …
    • Directorycore/ Constructs genéricos reutilizados pelos constructs em app

      • …
    • index.ts Ponto de entrada exportando os constructs de app
  • project.json Metas de build e configuração do projeto

Projeto gerado

Este projeto é gerado usando o gerador ts#project e portanto configura as mesmas metas de build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Módulos Terraform para infraestrutura específica de um projeto/gerador

      • …
    • Directorycore/ Módulos genéricos reutilizados pelos módulos em app

      • …
  • project.json Metas de build e configuração do projeto

Projeto gerado

Este projeto é gerado usando o gerador terraform#project e portanto configura as mesmas metas de build.

Para implantar seu Agente Strands, os seguintes arquivos são gerados:

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directoryagents

      • Directory<project-name>

        • <project-name>.ts Construct CDK para implantar seu agente

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directoryagents

      • Directory<project-name>

        • <project-name>.tf Módulo para implantar seu agente
  • Directorycore

    • Directoryagent-core

      • runtime.tf Módulo genérico para implantação no Bedrock AgentCore Runtime

computeType = None

Se você selecionou None para computeType, nenhum construct CDK ou módulo Terraform é gerado — o Agente Strands só pode ser executado localmente.

Trabalhando com Seu Agente Strands

Adicionando Ferramentas

Ferramentas são funções que o agente de IA pode chamar para executar ações. O framework Strands usa uma abordagem simples baseada em decoradores para definir ferramentas.

Você pode adicionar novas ferramentas no arquivo agent.py:

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],
)

O framework Strands trata automaticamente:

• Validação de tipos baseada nas dicas de tipo da função
• Geração de schema JSON para chamadas de ferramentas
• Tratamento de erros e formatação de respostas

Usando Ferramentas Pré-construídas

Strands fornece uma coleção de ferramentas pré-construídas através do pacote strands-tools:

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],
)

Configuração de Modelo

Por padrão, agentes Strands usam Claude 4 Sonnet, mas você pode personalizar o provedor de modelo. Consulte a documentação do Strands sobre provedores de modelos para opções de configuração:

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)

Consumindo Servidores MCP

Você pode adicionar ferramentas de servidores MCP ao seu agente Strands.

Para consumir servidores MCP criados usando os geradores py#mcp-server ou ts#mcp-server, você pode usar o gerador connection.

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - connection
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

Consulte o guia do gerador connection para detalhes sobre como a conexão é configurada.

Para outros servidores MCP, consulte a Documentação do Strands.

Mais

Para um guia mais detalhado sobre escrita de agentes Strands, consulte a documentação do Strands.

Protocolo

O protocolo de servidor do seu agente determina como ele se comunica. Todas as opções são servidas pelo FastAPI — o ponto de entrada difere:

• HTTP (padrão): Um servidor FastAPI padrão com um endpoint /invocations personalizado, CORS e streaming. Melhor para integrações de clientes personalizados.
• A2A: O Strands A2A Server montado em uma aplicação FastAPI. Melhor quando seu agente precisa ser descoberto e invocado por outros agentes compatíveis com A2A.
• AG-UI: A integração ag-ui-strands, que expõe o protocolo AG-UI via SSE. Melhor para integração direta com frontend usando CopilotKit em um website React.

Todos os protocolos expõem /ping para o contrato de verificação de saúde do runtime AgentCore. Agentes A2A escutam na porta 9000; agentes HTTP e AG-UI escutam na porta 8080. O Dockerfile e a infraestrutura gerados são configurados para você.

protocol = HTTP

Servidor FastAPI (protocolo HTTP)

O servidor HTTP gerado inclui:

• Configuração da aplicação FastAPI com middleware CORS
• Middleware de tratamento de erros
• Geração de schema OpenAPI
• Endpoint de verificação de saúde (/ping)
• Endpoint de invocação do agente (/invocations)

Personalizando Entradas e Saídas de Invocação com Pydantic

O endpoint de invocação do agente usa modelos Pydantic para definir e validar os schemas de requisição e resposta. Você pode personalizar esses modelos em main.py para atender aos requisitos do seu agente.

Definindo Modelos de Entrada

O modelo padrão InvokeInput aceita uma mensagem.

from pydantic import BaseModel

class InvokeInput(BaseModel):
    message: str

Você pode estender este modelo para incluir quaisquer campos adicionais que seu agente necessite.

O ID de sessão é extraído do cabeçalho HTTP x-amzn-bedrock-agentcore-runtime-session-id, consistente com o contrato de sessão do Bedrock AgentCore Runtime. Se o cabeçalho não for fornecido, um UUID aleatório é gerado como fallback.

Organização do código

Você provavelmente desejará abstrair parte ou todo o ID de sessão do chamador se os usuários forem invocar seu agente diretamente. Por exemplo, você pode usar o ID do usuário autenticado como parte do ID de sessão.

Também vale a pena notar que, dependendo do seu caso de uso, você pode precisar implementar autorização para sessões, por exemplo, garantindo que os usuários possam acessar apenas suas próprias sessões e não as de outros usuários.

Definindo Modelos de Saída

Para respostas em streaming, o gerador fornece JsonStreamingResponse que serializa automaticamente modelos Pydantic para o formato JSON Lines (application/jsonl). Este formato é compatível com a especificação de streaming do OpenAPI 3.2 e funciona perfeitamente com o cliente TypeScript gerado.

Por padrão, o agente produz objetos StreamChunk contendo o texto de resposta do agente:

class StreamChunk(BaseModel):
    content: str

Você pode personalizar o modelo StreamChunk para atender às suas necessidades:

from pydantic import BaseModel

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

Limitação de streaming do FastAPI

Note que como o FastAPI atualmente não suporta a geração de uma especificação OpenAPI para respostas em streaming, devemos definir explicitamente o modelo de resposta para cada operação de streaming, ou seja:

@app.post(
    "/invocations",
    response_class=JsonStreamingResponse,
    responses={200: JsonStreamingResponse.openapi_response(StreamChunk)},
)
async def invoke(input: InvokeInput) -> JsonStreamingResponse:
    return JsonStreamingResponse(handle_invoke(input))

Existe uma solicitação de recurso aberta para suporte nativo no FastAPI.

Bedrock AgentCore Python SDK

O gerador inclui uma dependência no Bedrock AgentCore Python SDK para as constantes PingStatus. Se desejar, é simples usar BedrockAgentCoreApp em vez de FastAPI, porém note que a segurança de tipos é perdida.

Você pode encontrar mais detalhes sobre as capacidades do SDK na documentação aqui.

Infraestrutura como código

Como o gerador fornece infraestrutura CDK ou Terraform que gerencia a implantação do seu agente, você não precisa utilizar o bedrock-agentcore-starter-toolkit mencionado na documentação para implantar seu agente.

protocol = A2A

Servidor A2A (protocolo A2A)

O main.py gerado monta A2AServer.to_fastapi_app() em uma aplicação FastAPI pai que também expõe /ping. Quando implantado no AgentCore, o ponto de entrada resolve o ARN público do runtime do AppConfig e o anuncia no cartão do agente.

A maioria dos usuários não precisará modificar este arquivo — edite agent.py para alterar ferramentas ou o prompt do sistema. O servidor A2A popula o cartão do agente (/.well-known/agent-card.json) a partir do name e description do construtor Agent.

protocol = AG-UI

Servidor AG-UI (protocolo AG-UI)

O main.py gerado envolve seu Agent Strands em um ag_ui_strands.StrandsAgent e cria uma aplicação FastAPI via create_strands_app(). A aplicação resultante expõe um único endpoint POST que transmite eventos AG-UI via Server-Sent Events (SSE), além de /ping para a verificação de saúde do runtime AgentCore.

A maioria dos usuários não precisará modificar este arquivo — edite agent.py para alterar ferramentas ou o prompt do sistema.

Conectar a um website React

Agentes AG-UI são projetados para serem consumidos diretamente por um frontend. Use o gerador connection para conectar seu website React ao agente com um provedor CopilotKit e cliente AG-UI HttpAgent.

Executando Seu Agente Strands

Desenvolvimento Local

O gerador configura um alvo chamado <your-agent-name>-serve, que inicia seu Agente Strands localmente para desenvolvimento e testes.

pnpm

pnpm nx agent-serve your-project

yarn

yarn nx agent-serve your-project

npm

npx nx agent-serve your-project

bun

bunx nx agent-serve your-project

Este comando usa uv run para executar seu Agente Strands usando o Bedrock AgentCore Python SDK.

Converse com Seu Agente

O gerador configura um alvo Nx <your-agent-name>-chat que depende de <your-agent-name>-serve-local. Executá-lo inicia o agente localmente e o coloca em um chat interativo de terminal:

pnpm

pnpm nx run your-project:agent-chat

yarn

yarn nx run your-project:agent-chat

npm

npx nx run your-project:agent-chat

bun

bunx nx run your-project:agent-chat

Para agentes HTTP, o gerador também emite:

• scripts/<your-agent-name>_openapi.py — um pequeno script que exporta a especificação OpenAPI do agente
• Um alvo Nx <your-agent-name>-openapi que o executa
• Um alvo Nx <your-agent-name>-generate-client que produz um cliente TypeScript com segurança de tipos em scripts/<your-agent-name>/generated/
• scripts/<your-agent-name>/chat.ts — um wrapper fino em torno do cliente gerado

Quando você personalizar a forma de entrada do agente (por exemplo, adicionar novos campos a InvokeInput), atualize chat.ts para passar os novos campos ao invocar o agente e o resto funciona automaticamente.

computeType = BedrockAgentCoreRuntime

Implantando Seu Agente Strands no Bedrock AgentCore Runtime

Infraestrutura como Código

Se você selecionou BedrockAgentCoreRuntime para computeType, a infraestrutura CDK ou Terraform relevante é gerada, que você pode usar para implantar seu Strands Agent no Amazon Bedrock AgentCore Runtime.

CDK

Um construto CDK é gerado para o seu agente, nomeado com base no name que você escolheu ao executar o gerador, ou <ProjectName>Agent por padrão.

Você pode usar este construto CDK em uma aplicação CDK:

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

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

Construto CDK Alpha

Este construto usa o módulo @aws-cdk/aws-bedrock-agentcore-alpha.

Terraform

Um módulo Terraform é gerado para você, nomeado com base no name que você escolheu ao executar o gerador, ou <ProjectName>-agent por padrão.

Passe as saídas do módulo runtime_config_appconfig compartilhado para o módulo do agente:

module "my_project_agent" {
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

Permissões de Modelo Bedrock

O construto de agente gerado concede permissão para invocar todos os modelos de fundação e perfis de inferência do Bedrock por padrão (bedrock:InvokeModel e bedrock:InvokeModelWithResponseStream em arn:aws:bedrock:*:*:foundation-model/* e arn:aws:bedrock:*:*:inference-profile/*).

Você pode querer restringir isso aos modelo(s) específico(s) que seu agente usa. Você pode encontrar o modelo padrão usado pelos agentes Strands na documentação do Strands; veja o guia de provedores de modelo Strands para configurar um modelo diferente.

Docker necessário

Docker é necessário para construir e implantar seu Strands Agent. Certifique-se de ter instalado e iniciado o Docker para evitar erros como:

ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.

Autenticação

O gerador fornece uma opção auth para configurar a autenticação para o seu Strands Agent. Você pode escolher entre autenticação IAM (padrão) ou Cognito ao gerar seu agente.

IAM

Por padrão, seu Strands Agent será protegido usando autenticação IAM, basta implantá-lo sem nenhum argumento:

CDK

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

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

Você pode conceder acesso para invocar seu agente no Bedrock AgentCore Runtime usando o método grantInvokeAccess, por exemplo:

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);
  }
}

Terraform

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

Para conceder acesso para invocar seu agente, você precisará adicionar uma política como a seguinte, referenciando a saída module.my_project_agent.agent_core_runtime_arn:

{
  Effect = "Allow"
  Action = [
    "bedrock-agentcore:InvokeAgentRuntime"
  ]
  Resource = [
    module.my_project_agent.agent_core_runtime_arn,
    "${module.my_project_agent.agent_core_runtime_arn}/*"
  ]
}

Autenticação Cognito

Quando você seleciona autenticação Cognito, o gerador configura o agente para usar Cognito para autenticação.

CDK

O construto gerado aceita uma propriedade identity que configura a autenticação Cognito:

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,
    });
  }
}

O construto UserIdentity pode ser gerado usando o gerador ts#react-website#auth, ou você pode criar seu próprio UserPool e UserPoolClient CDK.

Terraform

O módulo gerado aceita variáveis user_pool_id e user_pool_client_ids para autenticação Cognito:

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "my_project_agent" {
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

Provedores OIDC personalizados

Se você precisar de autenticação JWT personalizada com um provedor OIDC não-Cognito, você pode modificar o construto CDK gerado ou o módulo Terraform para o seu agente diretamente. Note que o gerador de conexão suportará apenas autenticação IAM ou Cognito.

Alvos Bundle e Docker

Para construir seu Agente Strands para o Bedrock AgentCore Runtime, um alvo bundle é adicionado ao seu projeto, que:

• Exporta suas dependências Python para um arquivo requirements.txt usando uv export
• Instala dependências para a plataforma alvo (aarch64-manylinux_2_28) usando uv pip install

Um alvo docker específico para seu Agente Strands também é adicionado, que copia o Dockerfile e os artefatos empacotados para um diretório de contexto docker. Isso co-localiza o Dockerfile com a saída construída, permitindo que o CDK construa a imagem Docker diretamente usando AgentRuntimeArtifact.fromAsset.

Observabilidade

Seu agente é configurado automaticamente com observabilidade usando o AWS Distro for Open Telemetry (ADOT), através da configuração de auto-instrumentação em seu Dockerfile.

Você pode encontrar traces no Console AWS CloudWatch, selecionando “GenAI Observability” no menu. Note que para os traces serem populados, você precisará habilitar o Transaction Search.

Para mais detalhes, consulte a documentação do AgentCore sobre observabilidade.

Invocando seu Agente Strands

protocol = HTTP

Invocar o Servidor Local

Para invocar um Agente executando localmente através do alvo <your-agent-name>-serve, você pode enviar uma requisição POST simples para /invocations na porta em que seu agente local está sendo executado. Por exemplo, com curl:

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

Flag de streaming do Curl

O argumento -N dado ao curl desabilita o buffering do fluxo de saída, para que você possa ver a resposta em streaming em tempo real.

Invocar o Agente Implantado

Para invocar seu Agent implantado no Bedrock AgentCore Runtime, você pode enviar uma requisição POST para o endpoint do dataplane do Bedrock AgentCore Runtime com seu ARN de runtime codificado em URL.

Você pode obter o ARN de runtime da sua infraestrutura da seguinte forma:

CDK

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,
    });
  }
}

Terraform

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

output "agent_arn" {
  value = module.my_project_agent.agent_core_runtime_arn
}

O ARN terá o seguinte formato: arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>.

Você pode então codificar o ARN em URL substituindo : por %3A e / por %2F.

Console do navegador

Isso é simples em um console do navegador ou Node REPL usando o método integrado encodeURIComponent:

encodeURIComponent('arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>')

A URL do dataplane do Bedrock AgentCore Runtime para invocar o agent é a seguinte:

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

A maneira exata de invocar esta URL depende do método de autenticação usado.

IAM

Autenticação IAM

Para Autenticação IAM, a requisição deve ser assinada usando AWS Signature Version 4 (SigV4).

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'

Clique aqui para mais detalhes sobre como configurar o comando acurl acima

Cognito

Autenticação JWT / Cognito

Para Autenticação Cognito, passe o Token de Acesso Cognito no cabeçalho Authorization:

curl -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" \
  -H "Authorization: Bearer <access-token>"

Você pode obter o token de acesso usando o comando cognito-idp admin-initiate-auth da AWS CLI, por exemplo:

aws cognito-idp admin-initiate-auth \
  --user-pool-id <user-pool-id> \
  --client-id <user-pool-client-id> \
  --auth-flow ADMIN_NO_SRP_AUTH \
  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
  --region <region> \
  --query 'AuthenticationResult.AccessToken' \
  --output text

Navegador / Website React

Para invocar seu Agente Strands a partir de um website React, você pode usar o gerador connection, que configura automaticamente um cliente com a autenticação correta (IAM ou Cognito).

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - connection
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

Consulte o guia do gerador connection para detalhes sobre como a conexão é configurada.

protocol = A2A

Invocando um Agente A2A como Ferramenta

Para delegar trabalho deste agente para um agente A2A remoto (seja TypeScript ou Python), use o gerador connection. Ele fornece um cliente autenticado com SigV4 para o agente alvo e transforma via AST o agent.py deste agente para registrar o agente A2A remoto como um delegado decorado com @tool.

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - connection
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

Consulte o guia do gerador connection para detalhes sobre como a conexão é configurada.

protocol = AG-UI

Invocando um Agente AG-UI

Para invocar seu agente AG-UI a partir de um website React, use o gerador connection, que configura um cliente CopilotKit configurado para seu agente implantado com a autenticação correta (IAM ou Cognito).

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - connection
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

Consulte o guia do gerador connection para detalhes sobre como a conexão é configurada.