Memulai tanpa AgentCore CLI

Anda dapat membuat agen AgentCore Runtime tanpa AgentCore CLI. Sebagai gantinya, Anda dapat menggunakan kombinasi alat baris perintah untuk mengonfigurasi dan menyebarkan agen Anda ke AgentCore Runtime.

Tutorial ini menunjukkan cara menerapkan agen kustom tanpa menggunakan AgentCore CLI. Agen kustom adalah agen yang dibuat tanpa menggunakan AgentCore Python SDK. Dalam tutorial ini, agen kustom dibangun menggunakan FastAp dan Docker. Agen kustom mengikuti persyaratan AgentCore Runtime, artinya agen harus mengekspos titik akhir /invocations POST dan /ping GET dan dikemas dalam wadah Docker. Amazon Bedrock AgentCore memerlukan arsitektur ARM64 untuk semua agen yang digunakan.

Pengaturan mulai cepat

Aktifkan observabilitas untuk agen Anda

Amazon Bedrock AgentCore Observability membantu Anda melacak, men-debug, dan memantau agen yang Anda host di Runtime. AgentCore Untuk mengamati agen, aktifkan Penelusuran CloudWatch Transaksi terlebih dahulu dengan mengikuti petunjuk di Mengaktifkan AgentCore observabilitas.

Instal uv

Untuk contoh ini, kita akan menggunakan manajer uv paket, meskipun Anda dapat menggunakan utilitas Python atau manajer paket. Untuk menginstal uv di macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Untuk petunjuk pemasangan pada platform lain, lihat dokumentasi uv.

Buat proyek agen Anda

Menyiapkan proyek Anda

Persyaratan kontrak agen

Agen kustom Anda harus memenuhi persyaratan inti ini:

Struktur proyek

Catatan: Untuk kenyamanan, contoh di bawah ini menggunakan FastTapi Server sebagai kerangka web server untuk menangani permintaan.

Proyek Anda harus memiliki struktur berikut:

my-custom-agent/
├── agent.py                 # FastAPI application
├── Dockerfile               # ARM64 container configuration
├── pyproject.toml           # Created by uv init
└── uv.lock                  # Created automatically by uv

Contoh agen untaian lengkap

Buat agent.py di root proyek Anda dengan konten berikut:

Contoh 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)

Implementasi ini:

Uji secara lokal

Menguji agen Anda

Buat dockerfile

Buat Dockerfile di root proyek Anda dengan konten berikut:

Contoh 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"]

Dockerfile ini:

Bangun dan terapkan gambar ARM64

Pengaturan docker buildx

Docker buildx memungkinkan Anda membuat gambar untuk arsitektur yang berbeda. Atur dengan:

docker buildx create --use

Bangun untuk ARM64 dan uji secara lokal

Membangun dan menguji gambar Anda

Buat repositori ECR dan terapkan

Menyebarkan ke ECR

Menyebarkan runtime agen

Buat file bernama deploy_agent.py dengan konten berikut:

Contoh 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']}")

Jalankan skrip untuk menyebarkan agen Anda:

uv run deploy_agent.py

Skrip ini menggunakan create_agent_runtime operasi untuk menyebarkan agen Anda ke Amazon Bedrock AgentCore. Pastikan untuk mengganti account-id dengan ID AWS akun Anda yang sebenarnya dan pastikan peran IAM memiliki izin yang diperlukan. Untuk informasi selengkapnya, lihat Izin IAM untuk AgentCore Runtime.

Panggil agen Anda

Buat file bernama invoke_agent.py dengan konten berikut:

Contoh 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)

Jalankan skrip untuk memanggil agen Anda:

uv run invoke_agent.py

Skrip ini menggunakan operasi InvokeAgentRuntime AWS SDK untuk mengirim permintaan ke agen yang Anda gunakan. Pastikan untuk mengganti account-id dan agentArn dengan nilai aktual Anda.

Jika Anda berencana mengintegrasikan agen Anda dengan OAuth, Anda tidak dapat menggunakan AWS SDK untuk menelepon. InvokeAgentRuntime Sebagai gantinya, buat permintaan HTTPS ke InvokeAgentRuntime. Untuk informasi selengkapnya, lihat Mengautentikasi dan mengotorisasi dengan Auth Masuk dan Auth Keluar.

Format respons yang diharapkan

Ketika Anda memanggil agen Anda, Anda akan menerima tanggapan seperti ini:

Contoh Sampel respon

{
  "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"
  }
}

Hentikan sesi runtime

Untuk menghentikan sesi berjalan sebelum dapat dikonfigurasi IdleRuntimeSessionTimeout (default pada 15 menit) dan menghemat biaya pelarian potensial, jalankan: stop_runtime_session

Buat file bernama stop_runtime_session.py dengan konten berikut:

Contoh 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"
)

Ringkasan AgentCore persyaratan Amazon Bedrock

Kesimpulan

Dalam panduan ini, Anda telah mempelajari cara:

Dengan mengikuti langkah-langkah ini, Anda dapat membuat dan menerapkan agen khusus yang memanfaatkan kekuatan Amazon Bedrock AgentCore sambil mempertahankan kontrol penuh atas implementasi agen Anda.