本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 开始使用 AgentCore Memory
Amazon Bedrock M AgentCore emory 允许您创建和管理用于存储人工智能代理对话上下文的 AgentCore 内存资源。本入门指南将指导您安装依赖项并实现短期和长期内存功能。这些说明使用 AgentCore CLI。
步骤如下所示：
1. 创建包含语义策略的 AgentCore 内存
1. 将事件（对话历史记录）写入内存资源
1. 从长期存储器中检索内存记录
有关其他示例，请参阅[亚马逊基岩 AgentCore 内存示例](memory-examples.md)。
## 先决条件
在开始之前，请确保你有：
+ ** Amazon 配置**了凭据的账户 (`aws configure`)
+ **已安装 Python 3.10\+ **
+ Node.js 已安装 20 个以上（用于 AgentCore CLI）
要开始使用亚马逊 Bedrock AgentCore Memory，请安装依赖项、创建 AgentCore CLI 项目并设置虚拟环境。以下命令可以直接在终端中运行。
```
npm install -g @aws/agentcore
agentcore create --project-name MemoryQuickstart --no-agent
cd MemoryQuickstart
python -m venv .venv
source .venv/bin/activate
pip install bedrock-agentcore
```
C AgentCore LI 提供用于创建和管理内存资源的命令。`agentcore add memory`用于创建内存，并在`agentcore deploy`其中进行配置 Amazon。要进行事件操作和会话管理，请使用 AgentCore Python 软件开发工具包 (`bedrock-agentcore`)。
**注意**
C AgentCore LI 可帮助您创建和部署内存资源。有关直接服务 API 操作，请参阅 Boto3 文档：bedrock-agentcore-control 和 b [ edrock ](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore-control.html)-agentcore。[https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore.html](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore.html)
**完整示例：**查看演示步骤 1-3 的[亚马逊 Bedrock 示 AgentCore 例](https://github.com/awslabs/amazon-bedrock-agentcore-samples/tree/main/01-features/04-manage-context-of-your-agent/memory)。
## 第 1 步：创建 AgentCore 内存
你需要一个 AgentCore 内存来开始存储代理的信息。默认情况下，记忆事件（我们称之为短期记忆）可以写入 AgentCore 内存。为了提取见解并将其存入长期记忆记录，该资源需要一种*存储策略，*该配置定义了应如何处理对话数据以及要提取哪些信息（例如事实、偏好或摘要）。
在此步骤中，您将使用语义策略创建 AgentCore 内存，以便可以同时使用短期和长期内存。这将需要 2-3 分钟。您也可以在 Amazon 控制台中创建 AgentCore 内存资源。
使用语义策略创建内存：
**Example**
1.
```
agentcore add memory --name CustomerSupportSemantic --strategies SEMANTIC
agentcore deploy
```
1. 运行打开 `agentcore` TUI，然后选择 “**添加” ** 并选择 “**内存**”：
1. 输入内存名称：
1. 选择**语义**策略，然后确认：
然后运行`agentcore deploy`以配置内存 Amazon。
部署后，验证内存是否已创建：
```
agentcore status
```
## 第 2 步：将事件写入内存
您可以将事件作为短期 AgentCore 记忆写入记忆，并提取长期记忆的见解。
将事件写入内存有多种用途。首先，事件内容（最常见的对话历史）存储为短期记忆。其次，从事件中提取相关见解，并作为长期记忆的一部分写入记忆记录。
创建事件需要内存资源 ID、参与者 ID 和会话 ID。在此步骤中，您将创建三个事件，模拟最终用户和聊天机器人之间的消息。
```
import boto3
from bedrock_agentcore.memory import MemorySessionManager
from bedrock_agentcore.memory.constants import ConversationalMessage, MessageRole
control_client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')
# Retrieve the memory created in Step 1
response = control_client.list_memories()
memory = response['memories'][0]
memory_id = memory['id']
# Create a session to store memory events
session_manager = MemorySessionManager(
memory_id=memory_id,
region_name="us-west-2")
session = session_manager.create_memory_session(
actor_id="User1",
session_id="OrderSupportSession1"
)
# Write memory events (conversation turns)
session.add_turns(
messages=[
ConversationalMessage(
"Hi, how can I help you today?",
MessageRole.ASSISTANT)],
)
session.add_turns(
messages=[
ConversationalMessage(
"Hi, I am a new customer. I just made an order, but it hasn't arrived. The Order number is #35476",
MessageRole.USER)],
)
session.add_turns(
messages=[
ConversationalMessage(
"I'm sorry to hear that. Let me look up your order.",
MessageRole.ASSISTANT)],
)
```
撰写完特定演员的事件（回合）后，你可以获得这些事件（回合）。
```
# Get the last k turns in the session
turns = session.get_last_k_turns(k=5)
for turn in turns:
print(f"Turn: {turn}")
```
在这种情况下，你可以看到演员和会话的最后三个事件。
## 第 3 步：从长期内存中检索记录
将事件写入内存资源后，对其进行分析，并将有用的信息发送到长期存储器中。由于存储器包含语义长期记忆策略，因此系统提取并存储事实信息。
你可以使用以下命令列出所有内存记录：
```
# List all memory records
memory_records = session.list_long_term_memory_records(
namespace_path="/"
)
for record in memory_records:
print(f"Memory record: {record}")
print("--------------------------------------------------------------------")
```
或者在语义搜索中询问最相关的信息：
```
# Perform a semantic search
memory_records = session.search_long_term_memories(
query="can you summarize the support issue",
namespace_path="/",
top_k=3
)
```
有关用户的重要信息很可能存储在长期内存中。代理可以使用长期记忆而不是完整的对话历史记录来确保 LLM 的上下文不会过载。
## 向现有代理添加内存
如果您创建了一个没有内存的 Strands 代理并想稍后添加，请按照以下步骤操作：
1. 为您的项目添加内存资源：
```
agentcore add memory --name MyMemory --strategies SEMANTIC,SUMMARIZATION
agentcore deploy
```
1. 在您的代理中创建`memory/`目录：
```
mkdir -p app/MyAgent/memory
```
1. 创建`app/MyAgent/memory/session.py`：
```
import os
from typing import Optional
from bedrock_agentcore.memory.integrations.strands.config import AgentCoreMemoryConfig, RetrievalConfig
from bedrock_agentcore.memory.integrations.strands.session_manager import AgentCoreMemorySessionManager
MEMORY_ID = os.getenv("MEMORY_MYMEMORY_ID")
REGION = os.getenv("AWS_REGION")
def get_memory_session_manager(session_id: str, actor_id: str) -> Optional[AgentCoreMemorySessionManager]:
if not MEMORY_ID:
return None
retrieval_config = {
f"/users/{actor_id}/facts": RetrievalConfig(top_k=3, relevance_score=0.5),
f"/summaries/{actor_id}/{session_id}": RetrievalConfig(top_k=3, relevance_score=0.5)
}
return AgentCoreMemorySessionManager(
AgentCoreMemoryConfig(
memory_id=MEMORY_ID,
session_id=session_id,
actor_id=actor_id,
retrieval_config=retrieval_config,
),
REGION
)
```
1. 更新您的`main.py`以使用会话管理器：
```
from memory.session import get_memory_session_manager
@app.entrypoint
async def invoke(payload, context):
session_id = getattr(context, 'session_id', 'default-session')
user_id = getattr(context, 'user_id', 'default-user')
agent = Agent(
model=load_model(),
session_manager=get_memory_session_manager(session_id, user_id),
system_prompt="You are a helpful assistant.",
)
response = agent(str(payload.get("prompt", "")))
return response
```
1. 部署更新后的项目：
```
agentcore deploy
```
**注意**
每个内存资源都有一个环境变量`MEMORY__ID`（大写，带下划线），该变量将在部署后在代理的运行时环境中自动可用。
## 资源清理
当你使用完内存资源后，你可以将其删除：
```
agentcore remove memory --name CustomerSupportSemantic
agentcore deploy
```
## 后续步骤
请考虑以下事项：
+ [向现有 AgentCore 内存添加长期策略](long-term-enabling-long-term-memory.md#long-term-adding-strategies-to-existing-memory)向您的内存资源添加另一种策略。
+ [启用可观察性](memory-observability.md)，以便更清楚地了解内存的工作原理
+ 看看更多的[例子](memory-examples.md)。