# Comece sem a AgentCore CLI
Você pode criar um agente AgentCore Runtime sem a AgentCore CLI. Em vez disso, você pode usar uma combinação de ferramentas de linha de comando para configurar e implantar seu agente em um AgentCore Runtime.
Este tutorial mostra como implantar um agente personalizado sem usar a AgentCore CLI. Um agente personalizado é um agente criado sem usar o SDK do AgentCore Python. Neste tutorial, o agente personalizado é criado usando FastAPI e Docker. O agente personalizado segue os [requisitos AgentCore de tempo de execução](runtime-service-contract.md), o que significa que o agente deve expor os endpoints `/invocations` POST e `/ping` GET e ser empacotado em um contêiner Docker. O Amazon Bedrock AgentCore exige a arquitetura ARM64 para todos os agentes implantados.
**nota**
Você também pode usar essa abordagem para agentes que você cria com o SDK do AgentCore Python.
## Configuração de início rápido
### Habilite a observabilidade para seu agente
[O Amazon Bedrock AgentCore Observability](observability.md) ajuda você a rastrear, depurar e monitorar agentes que você hospeda no Runtime. AgentCore Para observar um agente, primeiro ative a Pesquisa de CloudWatch Transações seguindo as instruções em [Habilitando a AgentCore observabilidade](observability-configure.md#observability-configure-builtin).
### Instalar uv
Neste exemplo, usaremos o gerenciador de `uv` pacotes, embora você possa usar qualquer utilitário ou gerenciador de pacotes do Python. Para instalar `uv` no macOS:
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Para obter instruções de instalação em outras plataformas, consulte a [documentação do uv](https://docs.astral.sh/uv/getting-started/installation/).
### Crie seu projeto de agente
**Configurando seu projeto**
1. Crie e navegue até o diretório do seu projeto:
```
mkdir my-custom-agent && cd my-custom-agent
```
1. Inicialize o projeto com o Python 3.11:
```
uv init --python 3.11
```
1. Adicione as dependências necessárias (uv cria automaticamente um .venv):
```
uv add fastapi 'uvicorn[standard]' pydantic httpx strands-agents
```
## Requisitos do contrato do agente
Seu agente personalizado deve atender aos seguintes requisitos principais:
+ **/invocations Endpoint: endpoint** POST para interações com agentes (OBRIGATÓRIO)
+ **/ping Endpoint: endpoint** GET para verificações de saúde (OBRIGATÓRIO)
+ **Docker Container**: pacote de implantação em contêiner ARM64
## Estrutura do projeto
**Observação:** por conveniência, o exemplo abaixo usa o **FastAPI Server** como a estrutura do servidor Web para lidar com solicitações.
Seu projeto deve ter a seguinte estrutura:
```
my-custom-agent/
├── agent.py # FastAPI application
├── Dockerfile # ARM64 container configuration
├── pyproject.toml # Created by uv init
└── uv.lock # Created automatically by uv
```
## Exemplo completo de agente de filamentos
Crie `agent.py` na raiz do seu projeto com o seguinte conteúdo:
**Exemplo agent.py**
```
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Dict, Any
from datetime import datetime
from strands import Agent
app = FastAPI(title="Strands Agent Server", version="1.0.0")
# Initialize Strands agent
strands_agent = Agent()
class InvocationRequest(BaseModel):
input: Dict[str, Any]
class InvocationResponse(BaseModel):
output: Dict[str, Any]
@app.post("/invocations", response_model=InvocationResponse)
async def invoke_agent(request: InvocationRequest):
try:
user_message = request.input.get("prompt", "")
if not user_message:
raise HTTPException(
status_code=400,
detail="No prompt found in input. Please provide a 'prompt' key in the input."
)
result = strands_agent(user_message)
response = {
"message": result.message,
"timestamp": datetime.utcnow().isoformat()
}
return InvocationResponse(output=response)
except Exception as e:
raise HTTPException(status_code=500, detail=f"Agent processing failed: {str(e)}")
@app.get("/ping")
async def ping():
return {"status": "healthy"}
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8080)
```
Essa implementação:
+ Cria um aplicativo FastAPI com os endpoints necessários
+ Inicializa um agente Strands para processar mensagens do usuário
+ Implementa o endpoint `/invocations` POST para interações com agentes
+ Implementa o endpoint `/ping` GET para verificações de saúde
+ Configura o servidor para ser executado no host `0.0.0.0` e na porta `8080`
## Testar localmente
**Testando seu agente**
1. Execute o aplicativo:
```
uv run uvicorn agent:app --host 0.0.0.0 --port 8080
```
1. Teste o `/ping` endpoint (em outro terminal):
```
curl http://localhost:8080/ping
```
1. Teste o `/invocations` endpoint:
```
curl -X POST http://localhost:8080/invocations \
-H "Content-Type: application/json" \
-d '{
"input": {"prompt": "What is artificial intelligence?"}
}'
```
## Criar dockerfile
Crie `Dockerfile` na raiz do seu projeto com o seguinte conteúdo:
**Example Dockerfile**
```
# Use uv's ARM64 Python base image
FROM --platform=linux/arm64 ghcr.io/astral-sh/uv:python3.11-bookworm-slim
WORKDIR /app
# Copy uv files
COPY pyproject.toml uv.lock ./
# Install dependencies (including strands-agents)
RUN uv sync --frozen --no-cache
# Copy agent file
COPY agent.py ./
# Expose port
EXPOSE 8080
# Run application
CMD ["uv", "run", "uvicorn", "agent:app", "--host", "0.0.0.0", "--port", "8080"]
```
Este Dockerfile:
+ Usa uma imagem base ARM64 Python (exigida pelo Amazon Bedrock) AgentCore
+ Configura o diretório de trabalho
+ Copia os arquivos de dependências e instala dependências
+ Copia o código do agente
+ Expõe a porta 8080
+ Configura o comando para executar o aplicativo
## Crie e implante a imagem ARM64
### Configurar docker buildx
O Docker buildx permite criar imagens para diferentes arquiteturas. Configure-o com:
```
docker buildx create --use
```
### Crie para ARM64 e teste localmente
**Construindo e testando sua imagem**
1. Crie a imagem localmente para testar:
```
docker buildx build --platform linux/arm64 -t my-agent:arm64 --load.
```
1. Teste localmente com credenciais (os agentes da Strands precisam de AWS credenciais):
```
docker run --platform linux/arm64 -p 8080:8080 \
-e AWS_ACCESS_KEY_ID="$AWS_ACCESS_KEY_ID" \
-e AWS_SECRET_ACCESS_KEY="$AWS_SECRET_ACCESS_KEY" \
-e AWS_SESSION_TOKEN="$AWS_SESSION_TOKEN" \
-e AWS_REGION="$AWS_REGION" \
my-agent:arm64
```
### Crie um repositório ECR e implante
**Implantação no ECR**
1. Crie um repositório ECR:
```
aws ecr create-repository --repository-name my-strands-agent --region us-west-2
```
1. Faça login no ECR:
```
aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin account-id.dkr.ecr.us-west-2.amazonaws.com
```
1. Crie e envie para o ECR:
```
docker buildx build --platform linux/arm64 -t account-id.dkr.ecr.us-west-2.amazonaws.com/my-strands-agent:latest --push.
```
1. Verifique se a imagem foi enviada:
```
aws ecr describe-images --repository-name my-strands-agent --region us-west-2
```
## Tempo de execução do agente de implantação
Crie um arquivo chamado `deploy_agent.py` com o seguinte conteúdo:
**Exemplo deploy\_agent.py**
```
import boto3
client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')
response = client.create_agent_runtime(
agentRuntimeName='strands_agent',
agentRuntimeArtifact={
'containerConfiguration': {
'containerUri': 'account-id.dkr.ecr.us-west-2.amazonaws.com/my-strands-agent:latest'
}
},
networkConfiguration={"networkMode": "PUBLIC"},
roleArn='arn:aws:iam::account-id:role/AgentRuntimeRole',
lifecycleConfiguration={
'idleRuntimeSessionTimeout': 300, # 5 min, configurable
'maxLifetime': 1800 # 30 minutes, configurable
},
)
print(f"Agent Runtime created successfully!")
print(f"Agent Runtime ARN: {response['agentRuntimeArn']}")
print(f"Status: {response['status']}")
```
Execute o script para implantar seu agente:
```
uv run deploy_agent.py
```
Esse script usa a `create_agent_runtime` operação para implantar seu agente no Amazon Bedrock AgentCore. Certifique-se de {{account-id}} substituir pelo ID real da sua AWS conta e garantir que a função do IAM tenha as permissões necessárias. Para obter mais informações, consulte [Permissões do IAM para AgentCore tempo de execução](runtime-permissions.md).
## Invoque seu agente
Crie um arquivo chamado `invoke_agent.py` com o seguinte conteúdo:
**Exemplo invoke\_agent.py**
```
import boto3
import json
agent_core_client = boto3.client('bedrock-agentcore', region_name='us-west-2')
payload = json.dumps({
"input": {"prompt": "Explain machine learning in simple terms"}
})
response = agent_core_client.invoke_agent_runtime(
agentRuntimeArn='arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/myStrandsAgent-suffix',
runtimeSessionId='dfmeoagmreaklgmrkleafremoigrmtesogmtrskhmtkrlshmt', # Must be 33+ chars
payload=payload,
qualifier="DEFAULT"
)
response_body = response['response'].read()
response_data = json.loads(response_body)
print("Agent Response:", response_data)
```
Execute o script para invocar seu agente:
```
uv run invoke_agent.py
```
Esse script usa a operação do [InvokeAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html) AWS SDK para enviar uma solicitação ao seu agente implantado. Certifique-se de substituir {{account-id}} e {{agentArn}} com seus valores reais.
Se você planeja integrar seu agente ao OAuth, não pode usar o AWS SDK para fazer chamadas. `InvokeAgentRuntime` Em vez disso, faça uma solicitação HTTPS para InvokeAgentRuntime. Para obter mais informações, consulte [Autenticar e autorizar com Autenticação de Entrada e Autenticação de Saída.](runtime-oauth.md)
## Formato de resposta esperado
Ao invocar seu agente, você receberá uma resposta como esta:
**Exemplo de resposta de amostra**
```
{
"output": {
"message": {
"role": "assistant",
"content": [
{
"text": "# Artificial Intelligence in Simple Terms\n\nArtificial Intelligence (AI) is technology that allows computers to do tasks that normally need human intelligence. Think of it as teaching machines to:\n\n- Learn from information (like how you learn from experience)\n- Make decisions based on what they've learned\n- Recognize patterns (like identifying faces in photos)\n- Understand language (like when I respond to your questions)\n\nInstead of following specific step-by-step instructions for every situation, AI systems can adapt to new information and improve over time.\n\nExamples you might use every day include voice assistants like Siri, recommendation systems on streaming services, and email spam filters that learn which messages are unwanted."
}
]
},
"timestamp": "2025-07-13T01:48:06.740668"
}
}
```
## Parar sessão de tempo de execução
Para interromper a sessão em execução antes do configurável `IdleRuntimeSessionTimeout` (o padrão é de 15 minutos) e economizar em possíveis custos descontrolados, execute: `stop_runtime_session`
Crie um arquivo chamado `stop_runtime_session.py` com o seguinte conteúdo:
**Exemplo stop\_runtime\_session.py**
```
import boto3
agent_core_client = boto3.client('bedrock-agentcore', region_name='us-west-2')
response = agent_core_client.stop_runtime_session(
agentRuntimeArn='arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/myStrandsAgent-suffix',
runtimeSessionId='dfmeoagmreaklgmrkleafremoigrmtesogmtrskhmtkrlshmt',
qualifier="DEFAULT"
)
```
## Resumo dos AgentCore requisitos do Amazon Bedrock
+ **Plataforma**: Deve ser `linux/arm64`
+ **Endpoints**: `/invocations` POST e `/ping` GET são obrigatórios
+ **ECR**: as imagens devem ser implantadas no ECR
+ **Porta**: o aplicativo é executado na porta 8080
+ **Integração de strands**: usa o Strands Agent para processamento de IA
+ **Credenciais: os** agentes da Strands precisam de AWS credenciais para operação
## Conclusão
Neste guia, você aprendeu como:
+ Configure um ambiente de desenvolvimento para criar agentes personalizados
+ Crie um aplicativo FastAPI que implemente os endpoints necessários
+ Containerize seu agente para a arquitetura ARM64
+ Teste seu agente localmente
+ Implante seu agente no ECR
+ Crie um tempo de execução de agente no Amazon Bedrock AgentCore
+ Invoque seu agente implantado
+ Interromper a sessão de tempo de execução
Seguindo essas etapas, você pode criar e implantar agentes personalizados que aproveitam o poder do Amazon Bedrock AgentCore enquanto mantêm controle total sobre a implementação do seu agente.