Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Menggunakan DynamoDB sebagai backend penyimpanan untuk Strands Agents

Strands Agents adalah SDK open source yang mengambil pendekatan berbasis model untuk membangun agen AI dalam beberapa baris kode, dengan dukungan kelas satu untuk Amazon Bedrock dan penyedia model lainnya. Di antara blok penyusunnya adalah antarmuka penyimpanan terpadu: kontrak berorientasi byte (write,, readdelete,list) yang diucapkan oleh setiap subsistem stateful di SDK. Manajer Sesi mempertahankan snapshot percakapan melaluinya, Pengelola Memori menyimpan memori jangka panjang melaluinya, dan offloader konteks dan transkrip menggunakan operasi yang sama.

Paket strands-dynamodb-storage mengimplementasikan kontrak itu pada satu tabel DynamoDB, untuk Python dan. TypeScript Kunci penyimpanan yang / dipisahkan SDK dipetakan langsung ke model kunci DynamoDB: dua segmen pertama kunci menjadi kunci partisi dan sisanya menjadi kunci pengurutan, jadi operasi titik adalah panggilan item tunggal dan daftar awalan adalah partisi asliQuery, tidak pernah pemindaian tabel.

Fitur utama

Prasyarat

Penginstalan

Instal paket dari PyPI:

pip install strands-dynamodb-storage "strands-agents>=1.48.0"

Atau dari npm for TypeScript ( TypeScript paketnya adalah cermin paritas fitur):

npm install strands-dynamodb-storage

Buat tabel

Paket tidak memiliki CreateTable izin dan tidak pernah membuat infrastruktur: Anda membuat tabel terlebih dahulu, dengan pengaturan penandaan, cadangan, dan enkripsi Anda sendiri yang diterapkan. Tabel dengan kunci partisi string pk dan kunci pengurutan string sk adalah satu-satunya persyaratan:

aws dynamodb create-table \
  --table-name agent-storage \
  --attribute-definitions AttributeName=pk,AttributeType=S AttributeName=sk,AttributeType=S \
  --key-schema AttributeName=pk,KeyType=HASH AttributeName=sk,KeyType=RANGE \
  --billing-mode PAY_PER_REQUEST

Jika Anda berencana untuk menggunakan memori semantik, deklarasikan indeks vektor dalam perintah yang sama ini: nama indeks, dimensi, dan fungsi jarak tidak dapat diubah setelah pembuatan, jadi ukurlah dimensi ke model penyematan Anda. Paket README menunjukkan panggilan lengkap yang menyatakan indeks.

Pertahankan sesi agen

Serahkan penyimpanan ke manajer sesi agen Anda. SDK memberi ruang nama kunci, mengambil snapshot percakapan pada setiap pemanggilan, dan mengembalikannya saat sesi yang sama kembali:

from strands import Agent
from strands.session import SnapshotSessionManager
from strands_dynamodb_storage import DynamoDBStorage

storage = DynamoDBStorage("agent-storage", region_name="us-east-1")
session = SnapshotSessionManager(session_id="user-42", storage=storage)

agent = Agent(session_manager=session)
agent("Where did we leave off?")

Anda juga dapat mengatur penyimpanan sekali pada Agent dirinya sendiri. Setiap subsistem yang menerima penyimpanan kemudian mewarisinya, masing-masing ruang nama di bawah awalan kuncinya sendiri, sehingga satu tabel membawa status seluruh agen:

from strands.vended_plugins.context_offloader import ContextOffloader

agent = Agent(
    storage=storage,
    session_manager=SnapshotSessionManager(),  # persists under session/
    plugins=[ContextOffloader()],              # offloads oversized tool results under offloader/
)

Kontrak byte juga tersedia secara langsung. Kontraknya asinkron: di dalam agen SDK menggerakkannya untuk Anda, dan dalam skrip biasa Anda membungkus panggilan ke dalamasyncio.run:

import asyncio


async def main():
    await storage.write("session/user-42/notes", b"prefers aisle seats")
    keys = await storage.list("session/user-42/")


asyncio.run(main())

Memori jangka panjang semantik dengan indeks vektor

Ketekunan sesi memecahkan setengah dari masalah memori: agen Anda selamat dari restart dan melanjutkan percakapan. Bagian yang lebih sulit adalah mengingat sesuatu yang dikatakan pengguna kepada agen beberapa minggu yang lalu, dalam percakapan baru yang tidak berbagi kunci dengan yang lama, dan itu membutuhkan pencarian ingatan dengan makna daripada dengan kunci. Indeks vektor DynamoDB membawa pencarian tetangga terdekat ke tabel yang sama yang menyimpan status agen Anda (lihat). Menggunakan indeks vektor di DynamoDB

Contoh berikut menyematkan teks dengan Amazon Titan Text Embeddings V2 melalui Amazon Bedrock. Model mengembalikan 1.024 vektor dimensi secara default, sehingga indeks untuk contoh ini dibuat dengan 1.024 dimensi. Kode berikut mendefinisikan embed() fungsi yang digunakan contoh yang tersisa:

import json

import boto3

bedrock = boto3.client("bedrock-runtime", region_name="us-east-1")


def embed(text):
    response = bedrock.invoke_model(
        modelId="amazon.titan-embed-text-v2:0",
        body=json.dumps({"inputText": text, "dimensions": 1024}),
    )
    return json.loads(response["body"].read())["embedding"]

Menulis memori melampirkan penyematan dan metadata opsional di samping byte. Kode berikut membangun toko dengan awalan per penyewa, sehingga kunci men memories/m1 darat di partisi fisik: user/u1

from strands_dynamodb_storage import DynamoDBStorage, SearchQuery

storage = DynamoDBStorage("agent-storage", region_name="us-east-1", prefix="user/u1")

await storage.write(
    "memories/m1",
    b"prefers window seats on long flights",
    vector=embed("prefers window seats on long flights"),
    metadata={"kind": "preference"},
)

Mengingat dengan makna adalah satu panggilan, dicakup ke partisi yang sama:

results = await storage.search(SearchQuery(
    vector=embed("what are this user's seating preferences?"),
    top_k=5,
    pk="user/u1",  # the physical partition: the full key's first two segments
    filter={"kind": "preference"},
))

Perhatikan pk argumennya. Indeks vektor dipartisi dengan cara yang sama seperti tabel, dan setiap pencarian dicakup ke satu partisi, sehingga pencarian penyewa tidak pernah berkisar di atas memori penyewa lain, dan pekerjaan yang dilakukan setiap pencarian melacak ukuran memori penyewa itu daripada seluruh tabel. Perlu diingat bahwa nilai partisi disediakan oleh pemanggil, jadi ini adalah pelingkupan kueri daripada batas otorisasi: pemegang utama dynamodb:SearchVectors pada tabel dapat mencari partisi apa pun, dan kontrol akses penyewa termasuk dalam IAM dan lapisan aplikasi Anda.

Hasil mengembalikan yang paling mirip terlebih dahulu. Arah skor mentah mengikuti fungsi jarak indeks: lebih rendah lebih dekat untuk jarak kosinus dan Euclidean, dan lebih tinggi lebih mirip untuk produk titik.

Hubungkan memori ke agen

Dalam agen nyata, Anda ingin memori yang diambil mencapai model secara otomatis, dan Manajer Memori SDK menanganinya: ia mengambil entri yang relevan sebelum setiap panggilan model dan melipatnya ke dalam input model, dan mendaftarkan search_memory alat yang dapat dipanggil model sesuai permintaan. Memory Manager menerima objek apa pun yang mengimplementasikan MemoryStore protokol SDK. Paket tidak mengirimkannya, jadi Anda menentukan kelas kecil di aplikasi Anda sendiri yang disematkan pada tulis, disematkan pada pencarian, dan mengembalikan nilai: MemoryEntry

import uuid

from strands.memory import MemoryEntry
from strands_dynamodb_storage import DynamoDBStorage, SearchQuery


class DynamoDBMemoryStore:
    def __init__(self, storage, partition, embed):
        self.storage = storage
        self.partition = partition
        self.embed = embed  # the embed() function defined earlier
        self.name = "dynamodb"
        self.description = "Long-term memories in DynamoDB, searched by meaning"
        self.max_search_results = 3
        self.writable = True
        self.extraction = None

    async def add(self, content, metadata=None):
        await self.storage.write(
            f"memories/{uuid.uuid4().hex[:8]}",
            content.encode(),
            vector=self.embed(content),
            metadata=metadata,
        )

    async def search(self, query, options=None):
        results = await self.storage.search(SearchQuery(
            vector=self.embed(query),
            top_k=self.max_search_results,
            pk=self.partition,
            include_values=True,
        ))
        return [
            MemoryEntry(content=r.data.decode(), metadata=r.metadata)
            for r in results
            if r.data is not None
        ]

Kode berikut menyemai tiga memori dan menghubungkan toko ke agen, jadi memori yang diambil mencapai model tanpa kode orkestrasi di pihak Anda:

import asyncio

from strands import Agent
from strands.memory import MemoryManager

storage = DynamoDBStorage("agent-storage", region_name="us-east-1", prefix="user/u1")
store = DynamoDBMemoryStore(storage, partition="user/u1", embed=embed)


async def seed():
    await store.add("Prefers window seats on long flights")
    await store.add("Planning a trip to Tokyo in December")
    await store.add("Allergic to peanuts")


asyncio.run(seed())

memory = MemoryManager(stores=[store], add_tool_config=True)
agent = Agent(memory_manager=memory)
agent("Book me a flight seat for my December trip. Which seat should I pick?")

Menjalankan ini dengan meja langsung, agen memanggil alatnyasearch_memory, mencocokkan perjalanan Tokyo dan preferensi kursi jendela dari DynamoDB, dan merekomendasikan kursi jendela untuk penerbangan. M add_tool_config=True elewati juga mendaftarkan add_memory alat, sehingga model dapat menyimpan fakta baru melalui tabel yang sama dengan yang ditangkatnya.

Izin IAM yang diperlukan

Saat runtime, paket mengeluarkan empat operasi DynamoDB, ditambah SearchVectors saat Anda menggunakan pencarian semantik, dan operasi Amazon S3 hanya saat Anda mengonfigurasi offload, sehingga kebijakan IAM dengan hak istimewa terendah pendek. Ganti 111122223333 dengan Akun AWS ID Anda dan perbarui Wilayah agar sesuai dengan lingkungan Anda:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:PutItem",
        "dynamodb:GetItem",
        "dynamodb:DeleteItem",
        "dynamodb:Query"
      ],
      "Resource": "arn:aws:dynamodb:us-east-1:111122223333:table/agent-storage"
    }
  ]
}

Paket README membawa kebijakan lengkap, termasuk pernyataan tambahan untuk pencarian semantik, offload Amazon S3, dan pemanggilan model penyematan.

Pertimbangan-pertimbangan

Sumber daya tambahan