使用独立内存服务

创建仅内存项目。

运行以下命令以搭建仅内存项目。将 "My Project" 替换为您的项目名称。

agentengine create --memory-only --name "My Project"

该命令生成一个项目目录，其中仅包含 project-config.yaml文件，不包含 agent.yaml文件或工作区。

在平台上创建并选择项目。

1. 运行以下命令以注册项目。该命令会打印新项目ID：

   agentengine project create "My Project"

2. 选择处于活动状态的新项目。将 <project-id> 替换为上一个命令打印的项目ID ：

   agentengine auth login --project-id <project-id>

配置内存设置。

1. 打开 project-config.yaml文件，在 memory:区块下设立密钥名称和提取提供商。

2. 运行以下命令，设立项目所需的密钥：

   agentengine secret set MONGODB_URI --value "<value>" --project-id <project-id>
   agentengine secret set VOYAGE_API_KEY --value "<value>" --project-id <project-id>
   agentengine secret set ANTHROPIC_API_KEY --value "<value>" --project-id <project-id>

   将以下占位符值替换为：

   • <value>：密钥的值。

     • MONGODB_URI： Atlas 集群的连接字符串。

     • VOYAGE_API_KEY：您的 Voyage AI密钥。

     • ANTHROPIC_API_KEY：您的 LLM提供商密钥。

   • <project-id>：agentengine project create 命令返回的项目对象ID 。此标志是必需的，因为仅内存工作流程不包含 agents.yaml文件。

   如果您使用其他提供商，请将 ANTHROPIC_API_KEY 替换为您的 LLM提供商的密钥名称。

3. 存储内存配置：

   agentengine memory configure

配置内存服务器。

启动内存运行时并等待其准备就绪：

agentengine memory apply --wait

创建服务帐户并检索访问权限令牌。

1. 运行以下命令，为项目创建服务帐户：

   agentengine service-account create memory-service --project-id <project-id> --role PROJECT_OWNER

   将 <project-id> 占位符替换为您的项目ID。保存命令输出中的客户端ID和客户端密钥。 Atlas Agent Engine 仅显示客户端密钥一次。

2. 运行以下命令，用客户端ID和客户端密钥交换访问权限令牌：

   export ACCESS_TOKEN=$(curl --fail-with-body --silent --show-error \
     --user <client-id> \
     --data grant_type=client_credentials \
     "https://agentengine.mongodb.com/api/v1/oauth/token" | jq -er .access_token)

   将 <client-id> 占位符替换为您的客户端ID。 curl 会提示输入客户端密钥，但不进行回显。

   提示

   访问权限令牌的有效期为一小时。在当前令牌过期之前请求新令牌。

安装Python SDK。

使用在上一步中导出的访问权限令牌，从平台的私有注册表安装 agent-engine-sdk-memory包：

pip install agent-engine-sdk-memory \
  --extra-index-url "https://ignore:$ACCESS_TOKEN@agentengine.mongodb.com/api/v1/packages/python/simple"

uv pip install agent-engine-sdk-memory \
  --extra-index-url "https://ignore:$ACCESS_TOKEN@agentengine.mongodb.com/api/v1/packages/python/simple"

URL使用 username:password 格式。 ignore 是占位符用户名，因为注册表仅使用密码字段中的访问权限令牌进行身份验证。 $ACCESS_TOKEN 解析为您在上一步中导出的访问权限令牌。

记录和检索对话上下文。

在您的应用程序中，添加以下代码以创建客户端、绑定用户身份、记录发生的轮流，并在以后的对话中检索相关上下文：

from agent_engine_sdk_memory import (
    Memory,
    MemoryRequestContext,
)
# Create the client using your access token.
memory = Memory(service_account_token="<your-access-token>")
# Bind the user and session for this conversation.
chat = memory.bind(
    MemoryRequestContext(
        user_id="user_1",
        session_id="thread_123",
    )
)
# Record turns as they happen.
chat.record_turn(
    role="user",
    content="I always fly out of Boston.",
)
chat.record_turn(
    role="assistant",
    content="Got it, Boston is saved as your home airport.",
)
# In a later conversation, recall what matters.
later = memory.bind(
    MemoryRequestContext(
        user_id="user_1",
        session_id="thread_456",
    )
)
context = later.build_context(
    query="Where should the flight book from?"
)
hits = later.search("home airport", top_k=5)

搭建一个本地内存项目。

运行以下命令，搭建一个仅用于本地开发的内存项目。将 "My Project" 替换为您的项目名称：

agentengine create --memory-only --name "My Project"

该命令会写入一个 project-config.yaml文件，将 memory_only 设置为 true，并指定内存配置模式。

此命令不会生成 agent.yaml文件、agents/目录或代理运行时代码。不能将 --memory-only 标志与 --template、--llm、--memory 或 --open-egress 标志结合使用。

配置环境变量。

在项目目录中创建一个 .env文件，然后在该文件中设立以下变量：

• VOYAGE_API_KEY：对于 Voyage AI嵌入是必需的

• LLM提供商密钥，例如 ANTHROPIC_API_KEY：如果在 project-config.yaml 中启用了背景提取，则为必填项

您无需设立MONGODB_URI 变量。 agentengine dev up 命令会自动预配并连接到捆绑的本地MongoDB容器。如果要使用外部MongoDB实例，设立此变量。

启动本地堆栈。

在项目目录中，运行以下命令以启动本地内存堆栈：

agentengine dev up

对于仅内存项目，此命令仅启动以下容器：

• mongodb：本地 Atlas 兼容的MongoDB实例

• memory-server：内存运行时服务

• oe：SDK 连接的本地业务流程引擎代理

命令输出包括本地 oe 和 memory-server 服务的 URL。复制 oe URL以在后续步骤中使用。

使用以下命令管理本地堆栈：

安装 agentic-platform-memory包。

运行以下命令以安装 agentic-platform-memory包：

pip install agentic-platform-memory

将 SDK 连接到本地堆栈。

导航到您的Python应用程序目录。此目录可以与您在第一步中创建的项目目录分开。

然后，通过将以下代码添加到应用程序来连接到本地堆栈。将 http://localhost:<oe-port> 替换为从 agentengine dev up 命令输出中复制的URL 。

from agentic_platform_memory import Memory, MemoryRequestContext
# Set the base_url to the local oe URL printed by "agentengine dev up".
memory = Memory(base_url="http://localhost:<oe-port>")
# Bind conversation identity.
session = memory.bind(
    MemoryRequestContext(
        user_id="user_123",
        session_id="session_456",
    )
)
# Record a turn.
session.record_turn(role="user", content="I prefer window seats on flights.")
# Build context.
context = session.build_context(
    query="What seat preferences are known?",
    enabled_sources={"stm", "semantic", "episodic"},
)
print(context.formatted_context)