# Comece a usar o Amazon Bedrock AgentCore
<a name="agentcore-get-started-cli"></a>

Esse guia de início rápido leva você de zero a um agente em execução em alguns minutos usando a AgentCore CLI. Você instalará a CLI, estruturará um projeto, testará localmente, implantará e invocará seu AWS agente.

Duas maneiras de criar um agente na AgentCore mesma CLI:
+  **Arnês gerenciado**. Você declara o agente em um arquivo de configuração (modelo, prompt, ferramentas, memória) e AgentCore executa o loop para você. Sem estrutura, sem código de orquestração. Bom caminho quando você quer o caminho mais rápido da ideia para um agente em execução. [Saiba mais](harness.md).
+  **Code-based agente**. Você escreve o loop do agente em Python usando uma estrutura que você já conhece (Strands LangGraph, Google ADK ou OpenAI Agents) e a implanta no Runtime. AgentCore Controle total sobre a lógica de orquestração.

Esta página mostra o fluxo baseado em código. Para arnês, consulte [O que é o AgentCore arnês](harness.md).

## Inscreva-se para um AWS account
<a name="sign_up_for_an_shared_id_aws_account"></a>

### Inscreva-se para um AWS account
<a name="sign-up-for-aws"></a>

Para começar AWS, você precisa de uma AWS conta. Para obter informações sobre como criar uma AWS conta, consulte [Introdução a uma AWSAWS conta](https://docs.aws.amazon.com/accounts/latest/reference/getting-started.html) *no Guia de referência de gerenciamento de contas*.

## Pré-requisitos
<a name="agentcore-cli-prerequisites"></a>
+  **Node.js 20 ou mais tarde.** A AgentCore CLI é distribuída como um pacote npm. Verifique com`node --version`. Instale a partir de [nodejs.org](https://nodejs.org), se necessário.
+  **npm.** Incluído com Node.js.
+  **Uma AWS conta com credenciais configuradas.** Configure via AWS CLI, variáveis de ambiente ou um AWS perfil. Consulte [Configuração da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).
+  **Python 3.10 ou posterior** (para código de agente). Verifique com`python3 --version`.
+  **Permissões do IAM**. Sua identidade precisa de permissões para fazer chamadas de AgentCore API e assumir as funções de bootstrap do CDK usadas durante a implantação. Consulte [AgentCore Permissões do CLI IAM](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/security-iam.html).

## Etapa 1: instalar a AgentCore CLI
<a name="agentcore-cli-install"></a>

```
npm install -g @aws/agentcore
```

Verificar:

```
agentcore --version
```

Para atualizar mais tarde, execute novamente o comando de instalação ou. `agentcore update` Fonte e problemas: [agentcore-cli](https://github.com/aws/agentcore-cli) on. GitHub

## Etapa 2: Crie seu projeto
<a name="agentcore-cli-create"></a>

```
agentcore create
```

O assistente interativo pergunta primeiro o que você deseja criar:
+  **Harness** - Um loop de agente gerenciado baseado em configuração. Não é necessário código de estrutura ou orquestração. Veja [o que é o AgentCore arnês.](harness.md)
+  **Agente - Um agente** baseado em código usando uma estrutura de sua escolha, implantada no Runtime. AgentCore 
+  **Ignorar** - Crie a estrutura do projeto sem um agente. Adicione um mais tarde com`agentcore add`.

Se você escolher **Agente**, o assistente continuará com:
+  **Estrutura** — Strands Agents (recomendado) LangChain/LangGraph, Google Agent Development Kit ou OpenAI Agents SDK
+  **Fornecedor de modelos:** Amazon Bedrock, Anthropic, OpenAI ou Gemini
+  **Memória** - Nenhuma, apenas de curto prazo ou de longo e curto prazo
+  **Tipo de compilação** - CodeZip (padrão) ou contêiner

Você também pode passar sinalizadores diretamente para criar um agente baseado em código:

```
agentcore create \
  --name MyAgent \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --build CodeZip
```

### Estrutura do projeto
<a name="agentcore-cli-project-structure"></a>

 `agentcore create`gera:

```
MyAgent/
├── agentcore/
│   ├── agentcore.json      # Project and resource configuration
│   ├── aws-targets.json    # Deployment target (account and region)
│   └── cdk/                # CDK infrastructure (auto-managed)
└── app/
    └── MyAgent/            # Your agent code
        ├── main.py         # Agent entrypoint
        ├── pyproject.toml  # Python dependencies
        └── ...
```

Arquivos principais:
+  `agentcore/agentcore.json`- a configuração principal. Define seus agentes, armazenamentos de memória, gateways, credenciais e outros recursos. Gerenciado por `agentcore add` `agentcore remove` e.
+  `app/`- seu código de agente. Cada agente obtém seu próprio subdiretório com um ponto de entrada e um. `pyproject.toml`
+  `agentcore/aws-targets.json`- a AWS conta e a região para implantação.

## Etapa 3: testar localmente
<a name="agentcore-cli-test"></a>

```
cd MyAgent
agentcore dev
```

 `agentcore dev`cria um ambiente virtual Python, instala dependências, inicia um servidor local com hot reload e abre o **inspetor de agentes em seu navegador para que você possa conversar com o agente, inspecionar** rastreamentos e navegar pelos recursos do projeto. As alterações no código são coletadas automaticamente.

Sinalizadores úteis:
+  `--no-browser`- use a TUI baseada em terminal em vez do inspetor do navegador.
+  `--no-traces`- desative os traços de gravação em`agentcore/.cli/traces`.
+  `--logs`- registros do servidor de cauda no modo não interativo.
+  `--port <N>`- fixe a porta de desenvolvimento (padrão 8080 para HTTP, 8000 para MCP, 9000 para A2A; incrementa automaticamente se estiver ocupada).

## Etapa 4: implantar seu agente
<a name="agentcore-cli-deploy"></a>

```
agentcore deploy
```

Implantar:

1. Empacota seu código em um artefato zip (ou cria um contêiner se) `--build Container`

1. Usa o AWS CDK nos bastidores para sintetizar e provisionar recursos

1. Cria um endpoint AgentCore Runtime para seu agente

1. Configura o CloudWatch registro e a observabilidade

A primeira implantação leva alguns minutos enquanto o CDK inicializa sua conta. As implantações subsequentes são mais rápidas.

Visualize o que mudará sem implantar:

```
agentcore deploy --dry-run
```

Verifique o status:

```
agentcore status
```

## Etapa 5: invocar seu agente implantado
<a name="agentcore-cli-invoke"></a>

```
agentcore invoke --prompt "Hello, what can you do?"
```

Se seu agente tiver pagamentos configurados, forneça o contexto do pagamento no momento da chamada:

```
agentcore invoke \
  --prompt "Access https://example-x402-merchant.com/paid-api" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --auto-session \
  --payment-user-id user@example.com
```

Esse é o loop. Itere`app/MyAgent/main.py`, teste com`agentcore dev`, implante com`agentcore deploy`, invoque com. `agentcore invoke`

## Adicione recursos ao seu projeto
<a name="agentcore-cli-add-capabilities"></a>

 `agentcore add`gerencia recursos em`agentcore.json`. Execute-o sem argumentos para o menu interativo ou direcione um recurso diretamente.

```
agentcore add memory        # Store conversation context
agentcore add agent         # Add a second agent to the same project
agentcore add gateway       # Connect external APIs/tools through Gateway
agentcore add credential    # Add an API key for a non-Bedrock provider
agentcore add evaluator     # Quality evaluation
agentcore add payment-manager   # Payments: create a payment manager
agentcore add payment-connector # Payments: link a payment provider
```

Cada comando add estrutura a configuração e solicita os valores necessários. Depois de adicionar, execute `agentcore deploy` para provisionar.

Mergulha profundamente nos recursos que você pode conectar:
+  [AgentCore Memória - memória](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html) de curto e longo prazo, estratégias de recuperação
+  [AgentCore Gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html) — conectividade controlada com APIs e servidores MCP
+  [AgentCore Navegador](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-tool.html) - navegação na web gerenciada para agentes
+  [AgentCore Interpretador de código](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/code-interpreter-tool.html) - execução de código em sandbox
+  [AgentCore Identidade](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity.html) — OAuth, provedores de credenciais de chave de API, identidade da carga de trabalho
+  [AgentCore Observabilidade](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html) - rastreamentos, registros e métricas em CloudWatch
+  [AgentCore VPC](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-vpc.html) - execute agentes dentro da sua VPC
+  [AgentCore Pagamentos - pagamentos](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments.html) por microtransação para agentes via x402

## Exibir registros e rastreamentos
<a name="agentcore-cli-logs"></a>

```
# Stream recent logs
agentcore logs

# Filter
agentcore logs --since 30m --level error
agentcore logs --query "timeout"

# List recent traces
agentcore traces list

# Get a specific trace
agentcore traces get <trace-id>
```

## Fazer a limpeza.
<a name="agentcore-cli-cleanup"></a>

```
agentcore remove all
agentcore deploy
```

 `remove all`redefine a configuração. O acompanhamento `deploy` detecta o estado vazio e destrói os recursos da sua conta.

## Próximas etapas
<a name="agentcore-cli-next-steps"></a>
+  [Qual é o AgentCore arnês](harness.md) - o caminho baseado em configuração para um agente em execução. Use qualquer modelo, conecte-se às ferramentas, mantenha o estado, implante em sua VPC e passe para o código quando precisar.
+  [AgentCore amostras de código](https://github.com/awslabs/amazon-bedrock-agentcore-samples) - exemplos de ponta a ponta em todas as estruturas e recursos.