메모리: MemoryService를 사용한 장기 지식¶
Session이 단일 대화의 기록(events) 및 임시 데이터(state)를 추적하는 반면, 에이전트는 과거 상호작용의 정보를 회상해야 할 수도 있습니다. 이것이 바로 장기 지식(Long-Term Knowledge)과 MemoryService의 개념이 필요한 부분입니다. 다음과 같이 생각할 수 있습니다:
Session/State: 특정 채팅 중의 단기 기억입니다.- 장기 지식(
MemoryService): 에이전트가 참조할 수 있는 검색 가능한 아카이브 또는 지식 라이브러리로, 여러 과거 채팅이나 기타 소스의 정보를 포함할 수 있습니다.
MemoryService 역할¶
BaseMemoryService(Go에서는 Service)는 이 검색 가능한 장기 지식 저장소를 관리하기 위한 인터페이스를 정의합니다. 다음 작업을 지원합니다:
- 정보 수집(Ingesting Information):
add_session_to_memory: 완료된Session을 가져와 관련 정보를 장기 지식 저장소에 추가합니다. 이 방식은 대화의 핵심을 자동으로 캡처하는 데 이상적입니다.add_events_to_memory: 전체 세션을 다시 수집하지 않고 이벤트 델타(예: 최신 턴)를 추가합니다. 장기 실행 세션 도중 메모리에 쓰고 싶을 때 유용합니다.add_memory: 명시적인MemoryEntry객체를 메모리에 직접 추가합니다. 이 메서드는 세밀한 제어를 제공하며 다른 소스의 특정 팩트를 주입할 때 유용합니다.
- 정보 검색(
search_memory): 에이전트(일반적으로Tool을 통해)가 지식 저장소를 쿼리하고 검색 쿼리를 기반으로 관련 스니펫이나 컨텍스트를 가져올 수 있도록 합니다.
add_events_to_memory와 add_memory는 선택 사항이며 모든 서비스에서 구현되는 것은 아니므로, 사용하기 전에 선택한 서비스가 이를 지원하는지 확인하세요.
올바른 메모리 서비스 선택¶
Python ADK는 세 가지 MemoryService 구현을 제공합니다. 아래 표를 사용하여 에이전트에 가장 적합한 것을 결정하세요.
| 기능 | InMemoryMemoryService | VertexAiMemoryBankService | VertexAiRagMemoryService |
|---|---|---|---|
| 지속성 | 없음(다시 시작하면 데이터가 손실됨) | 예(Agent Platform에서 관리) | 예(Knowledge Engine에 저장) |
| 주요 사용 사례 | 프로토타이핑, 로컬 개발 및 간단한 테스트. | 사용자 대화에서 의미 있고 진화하는 메모리를 구축합니다. | 전체 대화 코퍼스 또는 다른 RAG 색인 콘텐츠와 함께 벡터 검색을 수행합니다. |
| 메모리 추출 | 전체 대화 저장 | LLM을 기반으로 대화에서 의미 있는 정보를 추출하고 기존 메모리와 통합합니다. | Knowledge Engine으로 색인된 전체 대화를 저장합니다. |
| 검색 기능 | 기본 키워드 일치. | 고급 시맨틱 검색. | Knowledge Engine 기반 벡터 유사도 검색. |
| 설정 복잡성 | 없음. 기본값입니다. | 낮음. Agent Platform의 Agent Runtime 인스턴스가 필요합니다. | 중간. Knowledge Engine이 필요합니다. |
| 종속성 | 없음. | Google Cloud 프로젝트, Agent Platform API | Google Cloud 프로젝트, Knowledge Engine, Agent Platform SDK(선택 설치). |
| 사용 시기 | 프로토타이핑을 위해 여러 세션의 채팅 기록을 검색하려는 경우. | 에이전트가 과거 상호작용을 기억하고 학습하기를 원하는 경우. | 이미 RAG 인프라가 있거나 원시 대화 기록을 검색하려는 경우. |
google.adk.memory에서 VertexAiRagMemoryService를 항상 가져올 수 있지만, pip install google-adk[gcp]를 통해 Agent Platform SDK가 설치되어 있지 않으면 생성 시 ImportError가 발생합니다. Memory Bank와 RAG 기반 메모리는 아래의 Memory Bank 및 RAG 메모리에 설명되어 있습니다.
InMemoryMemoryService¶
InMemoryMemoryService는 애플리케이션의 메모리에 세션 정보를 저장하고 검색을 위해 기본 키워드 일치를 수행합니다. 설정이 필요 없으며 지속성이 필요하지 않은 프로토타이핑 및 간단한 테스트 시나리오에 가장 적합합니다.
예: 메모리 추가 및 검색
이 예는 단순성을 위해 InMemoryMemoryService를 사용하는 기본 흐름을 보여줍니다.
import asyncio
from google.adk.agents import LlmAgent
from google.adk.sessions import InMemorySessionService, Session
from google.adk.memory import InMemoryMemoryService # Import MemoryService
from google.adk.runners import Runner
from google.adk.tools import load_memory # Tool to query memory
from google.genai.types import Content, Part
# --- Constants ---
APP_NAME = "memory_example_app"
USER_ID = "mem_user"
MODEL = "gemini-flash-latest" # Use a valid model
# --- Agent Definitions ---
# Agent 1: Simple agent to capture information
info_capture_agent = LlmAgent(
model=MODEL,
name="InfoCaptureAgent",
instruction="Acknowledge the user's statement.",
)
# Agent 2: Agent that can use memory
memory_recall_agent = LlmAgent(
model=MODEL,
name="MemoryRecallAgent",
instruction="Answer the user's question. Use the 'load_memory' tool "
"if the answer might be in past conversations.",
tools=[load_memory] # Give the agent the tool
)
# --- Services ---
# Services must be shared across runners to share state and memory
session_service = InMemorySessionService()
memory_service = InMemoryMemoryService() # Use in-memory for demo
async def run_scenario():
# --- Scenario ---
# Turn 1: Capture some information in a session
print("--- Turn 1: Capturing Information ---")
runner1 = Runner(
# Start with the info capture agent
agent=info_capture_agent,
app_name=APP_NAME,
session_service=session_service,
memory_service=memory_service # Provide the memory service to the Runner
)
session1_id = "session_info"
await runner1.session_service.create_session(app_name=APP_NAME, user_id=USER_ID, session_id=session1_id)
user_input1 = Content(parts=[Part(text="My favorite project is Project Alpha.")], role="user")
# Run the agent
final_response_text = "(No final response)"
async for event in runner1.run_async(user_id=USER_ID, session_id=session1_id, new_message=user_input1):
if event.is_final_response() and event.content and event.content.parts:
final_response_text = event.content.parts[0].text
print(f"Agent 1 Response: {final_response_text}")
# Get the completed session
completed_session1 = await runner1.session_service.get_session(app_name=APP_NAME, user_id=USER_ID, session_id=session1_id)
# Add this session's content to the Memory Service
print("\n--- Adding Session 1 to Memory ---")
await memory_service.add_session_to_memory(completed_session1)
print("Session added to memory.")
# Turn 2: Recall the information in a new session
print("\n--- Turn 2: Recalling Information ---")
runner2 = Runner(
# Use the second agent, which has the memory tool
agent=memory_recall_agent,
app_name=APP_NAME,
session_service=session_service, # Reuse the same service
memory_service=memory_service # Reuse the same service
)
session2_id = "session_recall"
await runner2.session_service.create_session(app_name=APP_NAME, user_id=USER_ID, session_id=session2_id)
user_input2 = Content(parts=[Part(text="What is my favorite project?")], role="user")
# Run the second agent
final_response_text_2 = "(No final response)"
async for event in runner2.run_async(user_id=USER_ID, session_id=session2_id, new_message=user_input2):
if event.is_final_response() and event.content and event.content.parts:
final_response_text_2 = event.content.parts[0].text
print(f"Agent 2 Response: {final_response_text_2}")
# To run this example, you can use the following snippet:
# asyncio.run(run_scenario())
# await run_scenario()
import {
InMemoryMemoryService,
InMemorySessionService,
LOAD_MEMORY,
LlmAgent,
Runner
} from '@google/adk';
import { createUserContent } from '@google/genai';
// --- Constants ---
const APP_NAME = "memory_example_app";
const USER_ID = "mem_user";
const MODEL = "gemini-2.5-flash";
// --- Agent Definitions ---
// Agent 1: Simple agent to capture information
const infoCaptureAgent = new LlmAgent({
model: MODEL,
name: "InfoCaptureAgent",
instruction: "Acknowledge the user's statement concisely.",
});
// Agent 2: Agent that can use memory
const memoryRecallAgent = new LlmAgent({
model: MODEL,
name: "MemoryRecallAgent",
instruction: "Answer the user's question. Use the 'load_memory' tool if the answer might be in past conversations.",
tools: [LOAD_MEMORY]
});
// Export for 'adk run' compatibility (to avoid 'No BaseAgent found' error)
export const root_agent = memoryRecallAgent;
// --- Services ---
const sessionService = new InMemorySessionService();
const memoryService = new InMemoryMemoryService();
async function runScenario() {
// --- Turn 1: Capture some information in a session ---
console.log("--- Turn 1: Capturing Information ---");
const runner1 = new Runner({
agent: infoCaptureAgent,
appName: APP_NAME,
sessionService,
memoryService
});
const session1Id = "session_info";
await sessionService.createSession({ appName: APP_NAME, userId: USER_ID, sessionId: session1Id });
const userInput1 = createUserContent("My favorite project is Project Alpha.");
let finalResponseText = "(No final response)";
for await (const event of runner1.runAsync({ userId: USER_ID, sessionId: session1Id, newMessage: userInput1 })) {
// Capture any text response from the agent
if (event.author === infoCaptureAgent.name && event.content?.parts) {
const text = event.content.parts.map(p => p.text || "").join("").trim();
if (text) finalResponseText = text;
}
}
console.log(`Agent 1 Response: ${finalResponseText}`);
// Get the completed session and add to Memory
const completedSession1 = await sessionService.getSession({ appName: APP_NAME, userId: USER_ID, sessionId: session1Id });
console.log("\n--- Adding Session 1 to Memory ---");
if (completedSession1) {
await memoryService.addSessionToMemory(completedSession1);
console.log("Session added to memory.");
}
// --- Turn 2: Recall the information in a new session ---
console.log("\n--- Turn 2: Recalling Information ---");
const runner2 = new Runner({
agent: memoryRecallAgent,
appName: APP_NAME,
sessionService,
memoryService
});
const session2Id = "session_recall";
await sessionService.createSession({ appName: APP_NAME, userId: USER_ID, sessionId: session2Id });
const userInput2 = createUserContent("What is my favorite project?");
let finalResponseText2 = "(No final response)";
for await (const event of runner2.runAsync({ userId: USER_ID, sessionId: session2Id, newMessage: userInput2 })) {
// Capture any text response from the agent
if (event.author === memoryRecallAgent.name && event.content?.parts) {
const text = event.content.parts.map(p => p.text || "").join("").trim();
if (text) finalResponseText2 = text;
}
}
console.log(`Agent 2 Response: ${finalResponseText2}`);
// Exit immediately to prevent the ADK CLI from starting an interactive loop
process.exit(0);
}
// Execute the scenario
runScenario().catch(err => {
console.error(err);
process.exit(1);
});
import (
"context"
"fmt"
"log"
"strings"
"google.golang.org/adk/v2/agent"
"google.golang.org/adk/v2/agent/llmagent"
"google.golang.org/adk/v2/memory"
"google.golang.org/adk/v2/model/gemini"
"google.golang.org/adk/v2/runner"
"google.golang.org/adk/v2/session"
"google.golang.org/adk/v2/tool"
"google.golang.org/adk/v2/tool/functiontool"
"google.golang.org/genai"
)
const (
appName = "go_memory_example_app"
userID = "go_mem_user"
modelID = "gemini-2.5-flash"
)
// Args defines the input structure for the memory search tool.
type Args struct {
Query string `json:"query" jsonschema:"The query to search for in the memory."`
}
// Result defines the output structure for the memory search tool.
type Result struct {
Results []string `json:"results"`
}
// memorySearchToolFunc is the implementation of the memory search tool.
// This function demonstrates accessing memory via agent.Context.
func memorySearchToolFunc(tctx agent.Context, args Args) (Result, error) {
fmt.Printf("Tool: Searching memory for query: '%s'\n", args.Query)
// The SearchMemory function is available on the context.
searchResults, err := tctx.SearchMemory(context.Background(), args.Query)
if err != nil {
log.Printf("Error searching memory: %v", err)
return Result{}, fmt.Errorf("failed memory search")
}
var results []string
for _, res := range searchResults.Memories {
if res.Content != nil {
results = append(results, textParts(res.Content)...)
}
}
return Result{Results: results}, nil
}
// Define a tool that can search memory.
var memorySearchTool = must(functiontool.New(
functiontool.Config{
Name: "search_past_conversations",
Description: "Searches past conversations for relevant information.",
},
memorySearchToolFunc,
))
// This example demonstrates how to use the MemoryService in the Go ADK.
// It covers two main scenarios:
// 1. Adding a completed session to memory and recalling it in a new session.
// 2. Searching memory from within a custom tool using the agent.Context.
func main() {
ctx := context.Background()
// --- Services ---
// Services must be shared across runners to share state and memory.
sessionService := session.InMemoryService()
memoryService := memory.InMemoryService() // Use in-memory for this demo.
// --- Scenario 1: Capture information in one session ---
fmt.Println("--- Turn 1: Capturing Information ---")
infoCaptureAgent := must(llmagent.New(llmagent.Config{
Name: "InfoCaptureAgent",
Model: must(gemini.NewModel(ctx, modelID, nil)),
Instruction: "Acknowledge the user's statement.",
}))
runner1 := must(runner.New(runner.Config{
AppName: appName,
Agent: infoCaptureAgent,
SessionService: sessionService,
MemoryService: memoryService, // Provide the memory service to the Runner
}))
session1ID := "session_info"
must(sessionService.Create(ctx, &session.CreateRequest{AppName: appName, UserID: userID, SessionID: session1ID}))
userInput1 := genai.NewContentFromText("My favorite project is Project Alpha.", "user")
var finalResponseText string
for event, err := range runner1.Run(ctx, userID, session1ID, userInput1, agent.RunConfig{}) {
if err != nil {
log.Printf("Agent 1 Error: %v", err)
continue
}
if event.LLMResponse.Content != nil && !event.LLMResponse.Partial {
finalResponseText = strings.Join(textParts(event.LLMResponse.Content), "")
}
}
fmt.Printf("Agent 1 Response: %s\n", finalResponseText)
// Add the completed session to the Memory Service
fmt.Println("\n--- Adding Session 1 to Memory ---")
resp, err := sessionService.Get(ctx, &session.GetRequest{AppName: appName, UserID: userID, SessionID: session1ID})
if err != nil {
log.Fatalf("Failed to get completed session: %v", err)
}
if err := memoryService.AddSessionToMemory(ctx, resp.Session); err != nil {
log.Fatalf("Failed to add session to memory: %v", err)
}
fmt.Println("Session added to memory.")
// --- Scenario 2: Recall the information in a new session using a tool ---
fmt.Println("\n--- Turn 2: Recalling Information ---")
memoryRecallAgent := must(llmagent.New(llmagent.Config{
Name: "MemoryRecallAgent",
Model: must(gemini.NewModel(ctx, modelID, nil)),
Instruction: "Answer the user's question. Use the 'search_past_conversations' tool if the answer might be in past conversations.",
Tools: []tool.Tool{memorySearchTool}, // Give the agent the tool
}))
runner2 := must(runner.New(runner.Config{
Agent: memoryRecallAgent,
AppName: appName,
SessionService: sessionService,
MemoryService: memoryService,
}))
session2ID := "session_recall"
must(sessionService.Create(ctx, &session.CreateRequest{AppName: appName, UserID: userID, SessionID: session2ID}))
userInput2 := genai.NewContentFromText("What is my favorite project?", "user")
var finalResponseText2 string
for event, err := range runner2.Run(ctx, userID, session2ID, userInput2, agent.RunConfig{}) {
if err != nil {
log.Printf("Agent 2 Error: %v", err)
continue
}
if event.LLMResponse.Content != nil && !event.LLMResponse.Partial {
finalResponseText2 = strings.Join(textParts(event.LLMResponse.Content), "")
}
}
fmt.Printf("Agent 2 Response: %s\n", finalResponseText2)
}
import com.google.adk.agents.LlmAgent;
import com.google.adk.agents.RunConfig;
import com.google.adk.events.Event;
import com.google.adk.runner.InMemoryRunner;
import com.google.adk.sessions.Session;
import com.google.adk.tools.LoadMemoryTool;
import com.google.genai.types.Content;
import com.google.genai.types.Part;
import java.util.Optional;
public class MemoryExample {
public static void main(String[] args) {
String appName = "memory_example_app";
String userId = "mem_user";
String model = "gemini-flash-latest";
// An agent that can recall past information using the load_memory tool.
LlmAgent agent =
LlmAgent.builder()
.model(model)
.name("MemoryAgent")
.instruction(
"Answer the user's question. Use the 'load_memory' tool "
+ "if the answer might be in past conversations.")
.tools(new LoadMemoryTool())
.build();
// InMemoryRunner bundles in-memory session and memory services and shares
// them across every session it creates.
InMemoryRunner runner = new InMemoryRunner(agent, appName);
// --- Turn 1: capture information in one session ---
Session captureSession =
runner.sessionService().createSession(appName, userId).blockingGet();
Content statement =
Content.fromParts(Part.fromText("My favorite project is Project Alpha."));
runner
.runAsync(userId, captureSession.id(), statement, RunConfig.builder().build())
.blockingSubscribe();
// Persist the finished session to memory.
Session completedSession =
runner
.sessionService()
.getSession(appName, userId, captureSession.id(), Optional.empty())
.blockingGet();
runner.memoryService().addSessionToMemory(completedSession).blockingAwait();
// --- Turn 2: recall the information in a new session ---
Session recallSession =
runner.sessionService().createSession(appName, userId).blockingGet();
Content question = Content.fromParts(Part.fromText("What is my favorite project?"));
runner
.runAsync(userId, recallSession.id(), question, RunConfig.builder().build())
.blockingForEach(
(Event event) -> {
if (event.finalResponse()) {
event
.content()
.flatMap(Content::parts)
.ifPresent(
parts ->
parts.forEach(part -> part.text().ifPresent(System.out::println)));
}
});
}
}
/**
* This example demonstrates the basic flow using the `InMemoryMemoryService` in Kotlin.
* It shows how to capture information in one session, add it to memory, and recall it in another.
*/
fun main() =
runBlocking {
// --- Constants ---
val appName = "memory_example_app"
val userId = "mem_user"
val model = Gemini(name = "gemini-flash-latest")
// --- Agent Definitions ---
// Agent 1: Simple agent to capture information
val infoCaptureAgent =
LlmAgent(
name = "InfoCaptureAgent",
model = model,
instruction = Instruction("Acknowledge the user's statement."),
)
// Agent 2: Agent that can use memory
val memoryRecallAgent =
LlmAgent(
name = "MemoryRecallAgent",
model = model,
instruction =
Instruction(
"Answer the user's question. Use the 'load_memory' tool " +
"if the answer might be in past conversations.",
),
// Give the agent the tool
tools = listOf(LoadMemoryTool()),
)
// --- Services ---
// Services must be shared across runners to share state and memory
val sessionService = InMemorySessionService()
val memoryService = InMemoryMemoryService()
// --- Turn 1: Capturing Information ---
println("--- Turn 1: Capturing Information ---")
val runner1 =
InMemoryRunner(
agent = infoCaptureAgent,
appName = appName,
sessionService = sessionService,
memoryService = memoryService,
)
val sessionId1 = "session_info"
val userInput1 = Content.fromText(Role.USER, "My favorite project is Project Alpha.")
// Run the agent
runner1
.runAsync(
userId = userId,
sessionId = sessionId1,
newMessage = userInput1,
).collect { event ->
event.content?.parts?.forEach { part ->
if (!part.text.isNullOrBlank()) {
println("Agent Response: ${part.text}")
}
}
}
// Get the completed session using SessionKey
val session1 = sessionService.getSession(SessionKey(appName, userId, sessionId1))
// Add this session's content to the Memory Service
println("\n--- Adding Session 1 to Memory ---")
if (session1 != null) {
memoryService.addSessionToMemory(session1)
println("Session added to memory.")
}
// --- Turn 2: Recalling Information ---
println("\n--- Turn 2: Recalling Information ---")
val runner2 =
InMemoryRunner(
agent = memoryRecallAgent,
appName = appName,
// Reuse the same service
sessionService = sessionService,
// Reuse the same service
memoryService = memoryService,
)
val sessionId2 = "session_recall"
val userInput2 = Content.fromText(Role.USER, "What is my favorite project?")
// Run the second agent
runner2
.runAsync(
userId = userId,
sessionId = sessionId2,
newMessage = userInput2,
).collect { event ->
event.content?.parts?.forEach { part ->
if (!part.text.isNullOrBlank()) {
println("Agent Response: ${part.text}")
}
}
}
}
도구 내에서 메모리 검색¶
도구 컨텍스트를 사용하여 커스텀 도구 내에서 메모리를 검색할 수도 있습니다.
// Within a tool implementation
async runAsync({ args, toolContext }: RunAsyncToolRequest) {
const query = args['query'] as string;
const response = await toolContext.searchMemory(query);
// process response
return {
memories: response.memories.map(m => m.content.parts?.map(p => p.text).join(' ')).join('\n')
};
}
// memorySearchToolFunc is the implementation of the memory search tool.
// This function demonstrates accessing memory via agent.Context.
func memorySearchToolFunc(tctx agent.Context, args Args) (Result, error) {
fmt.Printf("Tool: Searching memory for query: '%s'\n", args.Query)
// The SearchMemory function is available on the context.
searchResults, err := tctx.SearchMemory(context.Background(), args.Query)
if err != nil {
log.Printf("Error searching memory: %v", err)
return Result{}, fmt.Errorf("failed memory search")
}
var results []string
for _, res := range searchResults.Memories {
if res.Content != nil {
results = append(results, textParts(res.Content)...)
}
}
return Result{Results: results}, nil
}
// Define a tool that can search memory.
var memorySearchTool = must(functiontool.New(
functiontool.Config{
Name: "search_past_conversations",
Description: "Searches past conversations for relevant information.",
},
memorySearchToolFunc,
))
suspend fun searchWithinTool(
context: ToolContext,
args: Map<String, Any>,
): String {
val query = args["query"] as String
val response =
context.invocationContext.memoryService?.searchMemory(
appName = context.invocationContext.session.key.appName,
userId = context.invocationContext.session.key.userId,
query = query,
)
// process response
return response?.memories?.joinToString("\n") {
it.content.parts.joinToString(" ") { p -> p.text ?: "" }
} ?: ""
}
Memory Bank¶
VertexAiMemoryBankService는 에이전트를 대화형 에이전트를 위한 정교하고 지속적인 메모리 기능을 제공하는 완전 관리형 Google Cloud 서비스인 Memory Bank에 연결합니다.
작동 방식¶
이 서비스는 두 가지 주요 작업을 처리합니다:
- 메모리 생성: 대화가 끝나면 세션의 이벤트를 Memory Bank로 보낼 수 있으며, Memory Bank는 정보를 지능적으로 처리하여 "메모리"로 저장합니다.
- 메모리 검색: 에이전트 코드는 Memory Bank에 대해 검색 쿼리를 실행하여 과거 대화에서 관련 메모리를 검색할 수 있습니다.
add_memory를 사용한 직접 메모리 수집¶
세션 기록에서 메모리를 생성하는 것 외에도 VertexAiMemoryBankService는 add_memory 메서드를 통한 직접 메모리 수집을 지원합니다. 이 메서드를 사용하면 Memory Bank에 저장되는 팩트를 정밀하게 제어할 수 있습니다.
작동 방식은 enable_consolidation 옵션에 따라 달라집니다:
-
직접 생성(기본값): 기본적으로
add_memory는 기본memories.createAPI를 호출합니다. 제공하는 각MemoryEntry는 별개의 독립된 메모리 항목으로 추가됩니다.from google.adk.memory import VertexAiMemoryBankService from google.adk.memory.memory_entry import MemoryEntry from google.genai.types import Content, Part memory_service = VertexAiMemoryBankService(...) await memory_service.add_memory( app_name="my-app", user_id="user-123", memories=[ MemoryEntry(content=Content(parts=[Part(text="The user's favorite color is blue.")])) ] ) -
통합을 통한 생성(Creation with Consolidation):
custom_metadata에서enable_consolidation을True로 설정하면 서비스는memories.generateAPI를 사용합니다. 이 설정을 통해 Memory Bank는 새로운 메모리 항목을 기존 관련 메모리와 지능적으로 통합하여 중복을 방지하고 보다 일관된 지식 기반을 구축할 수 있습니다.
전제 조건¶
이 기능을 사용하려면 다음이 있어야 합니다:
- Google Cloud 프로젝트: Agent Platform API가 활성화되어 있어야 합니다.
- Agent Runtime: Agent Platform에서 Agent Runtime을 생성해야 합니다. Memory Bank를 사용하기 위해 에이전트를 Agent Runtime에 배포할 필요는 없습니다. 이 설정을 통해 구성에 필요한 Agent Runtime ID를 얻을 수 있습니다.
-
인증: 로컬 환경이 Google Cloud 서비스에 액세스하도록 인증되었는지 확인합니다. 가장 간단한 방법은 다음을 실행하는 것입니다:
-
환경 변수: 이 서비스에는 Google Cloud 프로젝트 ID와 위치가 필요합니다. 이를 환경 변수로 설정하세요:
ADK 에이전트에서 Google Cloud에 연결하는 방법에 대한 자세한 내용은 Google Cloud 및 Agent Platform에 연결을 참조하세요.
구성¶
에이전트를 Memory Bank에 연결하려면 ADK 서버(adk web 또는 adk api_server)를 시작할 때 --memory_service_uri 플래그를 사용합니다. URI는 agentengine://<agent_engine_id> 형식이어야 합니다.
또는 VertexAiMemoryBankService를 수동으로 인스턴스화하고 Runner에 전달하여 Memory Bank를 사용하도록 에이전트를 구성할 수 있습니다.
/** Memory Bank keeps LLM-extracted memories in a Vertex AI Agent Engine. */
fun memoryBankRunner(agent: LlmAgent): InMemoryRunner {
val memoryService =
VertexAiMemoryBankService(
project = "PROJECT_ID",
location = "LOCATION",
agentEngineId = "AGENT_ENGINE_ID",
)
return InMemoryRunner(
agent = agent,
appName = "memory_bank_app",
memoryService = memoryService,
)
}
RAG 메모리¶
VertexAiRagMemoryService는 대화를 Knowledge Engine에 저장하고 벡터 유사도를 통해 검색합니다. 이미 RAG 인프라가 있거나 Memory Bank에서 생성된 LLM 추출 메모리 대신 원시 대화 기록 검색을 원할 때 사용하세요. Agent Platform SDK가 필요합니다.
/**
* RAG memory stores whole transcripts in a Knowledge Engine corpus and retrieves them by vector
* similarity.
*/
fun ragMemoryRunner(agent: LlmAgent): InMemoryRunner {
val memoryService =
VertexAiRagMemoryService(
project = "PROJECT_ID",
location = "LOCATION",
// A bare corpus id, NOT a full resource name. Kotlin expands it to
// projects/{project}/locations/{location}/ragCorpora/{id} and rejects an
// already-expanded name -- unlike the Python tab above, which takes the full name.
ragCorpus = "CORPUS_ID",
similarityTopK = 5,
vectorDistanceThreshold = 0.6,
)
return InMemoryRunner(
agent = agent,
appName = "rag_memory_app",
memoryService = memoryService,
)
}
에이전트에서 메모리 사용¶
메모리 서비스가 구성되면 에이전트는 도구 또는 콜백을 사용하여 메모리를 검색할 수 있습니다. ADK에는 메모리 검색을 위한 두 가지 기본 제공 도구가 포함되어 있습니다:
- 메모리 미리 로드(Preload memory): 콜백과 유사하게 각 턴이 시작될 때 메모리를 자동으로 검색합니다.
- 메모리 로드(Load memory): 에이전트가 도움이 될 것이라고 판단할 때 메모리를 검색합니다.
예:
세션에서 메모리를 추출하려면 add_session_to_memory를 호출해야 합니다. 예를 들어 콜백을 사용하여 이 단계를 자동화할 수 있습니다:
from google.adk.agents import Agent
from google.adk.tools import preload_memory
async def auto_save_session_to_memory_callback(callback_context):
await callback_context.add_session_to_memory()
agent = Agent(
model=MODEL,
name="Generic_QA_Agent",
instruction="Answer the user's questions",
tools=[preload_memory],
after_agent_callback=auto_save_session_to_memory_callback,
)
import { LlmAgent, PRELOAD_MEMORY, SingleAgentCallback } from '@google/adk';
const autoSaveSessionToMemoryCallback: SingleAgentCallback = async (callbackContext) => {
if (callbackContext.invocationContext.memoryService) {
await callbackContext.invocationContext.memoryService.addSessionToMemory(
callbackContext.invocationContext.session
);
}
};
const agent = new LlmAgent({
model: MODEL,
name: "Generic_QA_Agent",
instruction: "Answer the user's questions",
tools: [PRELOAD_MEMORY],
afterAgentCallback: autoSaveSessionToMemoryCallback,
});
ADK Go에서 에이전트 콜백은 메모리 서비스에 액세스할 수 없습니다. 대신 플러그인의 AfterRunCallback에서 세션을 저장하고, 메모리 서비스와 함께 러너에 플러그인을 등록하세요:
import (
"log"
"google.golang.org/adk/v2/agent"
"google.golang.org/adk/v2/agent/llmagent"
"google.golang.org/adk/v2/plugin"
"google.golang.org/adk/v2/runner"
"google.golang.org/adk/v2/tool"
"google.golang.org/adk/v2/tool/loadmemorytool"
)
autoSavePlugin, _ := plugin.New(plugin.Config{
Name: "auto_save_session_to_memory",
AfterRunCallback: func(ctx agent.InvocationContext) {
if m := ctx.Memory(); m != nil {
if err := m.AddSessionToMemory(ctx, ctx.Session()); err != nil {
log.Printf("failed to save session to memory: %v", err)
}
}
},
})
rootAgent, _ := llmagent.New(llmagent.Config{
Model: model,
Name: "Generic_QA_Agent",
Instruction: "Answer the user's questions",
Tools: []tool.Tool{loadmemorytool.New()},
})
r, _ := runner.New(runner.Config{
AppName: "my_app",
Agent: rootAgent,
SessionService: sessionService,
MemoryService: memoryService,
PluginConfig: runner.PluginConfig{
Plugins: []*plugin.Plugin{autoSavePlugin},
},
})
suspend fun autoSaveSessionToMemoryCallback(
context: CallbackContext,
): CallbackChoice<Unit, Content> {
context.addSessionToMemory()
return CallbackChoice.Continue(Unit)
}
fun agentWithCallback(model: Gemini) {
val agent =
LlmAgent(
model = model,
name = "Generic_QA_Agent",
instruction = Instruction("Answer the user's questions"),
tools = listOf(PreloadMemoryTool()),
afterAgentCallbacks = listOf(AfterAgentCallback(::autoSaveSessionToMemoryCallback)),
)
}
콜백에서 특정 이벤트 또는 팩트 쓰기¶
CallbackContext.addSessionToMemory 메서드는 메모리의 기본 동작이며 에이전트의 전체 세션을 저장합니다. 더 세밀한 제어가 필요한 경우 CallbackContext는 선택한 이벤트의 하위 집합을 위한 addEventsToMemory와 직접 구성한 팩트를 위한 addMemory의 두 가지 메서드를 추가로 제공합니다. 둘 다 선택적 customMetadata를 허용하며, 현재 호출에서 앱, 사용자 및 세션을 자동으로 채웁니다.
/**
* Saves a chosen set of events rather than the whole session, tagged so they can
* be filtered later. The events come from the caller: CallbackContext does not
* expose the session.
*/
suspend fun saveEventsToMemory(
context: CallbackContext,
events: List<Event>,
) {
// appName, userId and sessionId are taken from the invocation. Throws
// IllegalStateException if the runner has no memory service configured.
context.addEventsToMemory(events, customMetadata = mapOf("source" to "turn_callback"))
}
/** Writes an explicit fact, instead of letting the service derive one from events. */
suspend fun rememberPreferenceCallback(context: CallbackContext): CallbackChoice<Unit, Content> {
val preference = MemoryEntry(content = Content.fromText(Role.USER, "Prefers window seats."))
context.addMemory(listOf(preference))
return CallbackChoice.Continue(Unit)
}
세 가지 메서드 모두 러너에 메모리 서비스가 구성되어 있지 않은 경우 IllegalStateException을 발생시키므로 컴파일 시점이 아닌 런타임에 실패합니다.
메모리 기능 확장¶
BaseMemoryService를 확장한 메모리 서비스는 커스텀 메타데이터를 포함하여 에이전트 메모리에 세션 및 이벤트를 추가하는 기능을 지원합니다. 다음 코드 예시와 같이 InMemoryMemoryService와 같은 메모리 서비스의 add_session_to_memory 및 add_events_to_memory 메서드를 사용하여 메모리 데이터를 수정할 수 있습니다.
import asyncio
from google.adk.memory import InMemoryMemoryService
# Assume my_memory_service is an instance of InMemoryMemoryService
# and my_latest_events is a list of new adk.Event objects from the latest turn.
my_latest_events = [...]
async def update_incremental_memory(my_memory_service, my_latest_events):
# Example 1: Basic incremental update
await my_memory_service.add_events_to_memory(
app_name="my-app",
user_id="my-user",
events=my_latest_events,
session_id="my-optional-session-id"
)
# Example 2: Incremental update with Custom Metadata
await my_memory_service.add_events_to_memory(
app_name="my-app",
user_id="my-user",
events=my_latest_events,
session_id="my-optional-session-id",
custom_metadata={
"my_custom_key": "my_custom_value"
}
)
async def update_session_memory(my_memory_service, my_completed_session):
# Example 3: Applying custom metadata to a full session
await my_memory_service.add_session_to_memory(
session=my_completed_session,
custom_metadata={
"category": "user_preference"
}
)
고급 개념¶
실제 메모리 작동 방식¶
메모리 워크플로에는 다음 단계가 포함됩니다:
- 세션 상호작용: 사용자는
SessionService에서 관리하는Session을 통해 에이전트와 상호작용합니다. 이 상호작용 동안 이벤트가 기록되고 세션 상태가 업데이트될 수 있습니다. - 메모리로 수집: 세션이 종료되거나 중요한 정보를 캡처하면 애플리케이션은
memory_service.add_session_to_memory(session)을 호출합니다. 이 작업은 핵심 데이터를 추출하여 Agent Runtime Memory Bank와 같은 장기 지식 저장소에 영구 저장합니다. - 추후 쿼리: 다른 세션 또는 동일한 세션에서 과거 컨텍스트가 필요한 질문(예: "지난주에 프로젝트 X에 대해 무엇을 논의했나요?")을 할 수 있습니다.
- 에이전트의 메모리 도구 사용: 기본 제공
load_memory도구와 같은 메모리 검색 도구가 장착된 에이전트는 과거 컨텍스트의 필요성을 인식합니다. 검색 쿼리(예: "discussion project X last week")를 제공하여 도구를 호출합니다. - 검색 실행: 도구는 내부적으로
memory_service.search_memory(app_name=..., user_id=..., query=...)를 호출합니다. - 결과 반환:
MemoryService는 키워드 일치 또는 시맨틱 검색을 사용하여 저장소를 검색하고, 일치하는 스니펫을content와 선택 사항인id,author,timestamp,custom_metadata를 보유하는MemoryEntry객체 리스트가 포함된SearchMemoryResponse로 반환합니다. - 에이전트의 결과 사용: 도구는 일반적으로 컨텍스트 또는 함수 응답의 일부로 이 결과를 에이전트에 반환합니다. 그런 다음 에이전트는 이 검색된 정보를 사용하여 사용자에 대한 최종 답변을 작성할 수 있습니다.
에이전트가 둘 이상의 메모리 서비스에 액세스할 수 있나요?¶
- 표준 구성을 통해: 아니요. 프레임워크(
adk web,adk api_server)는--memory_service_uri플래그를 통해 한 번에 하나의 메모리 서비스로 구성되도록 설계되었습니다. 이 단일 서비스는 러너에 연결되며tool_context.search_memory()및callback_context.search_memory()를 통해 노출됩니다. - 에이전트 코드 내에서: 예. 두 번째
BaseMemoryService를 인스턴스화하고, 프레임워크에서 구성된 서비스를 위한ToolContext가 이미 있는 커스텀 도구에서 이를 참조할 수 있습니다.
예를 들어 에이전트는 대화 기록을 위해 프레임워크에서 구성된 InMemoryMemoryService를 사용하고, 별도의 지식 기반을 위해 VertexAiMemoryBankService, 문서 코퍼스 기반의 VertexAiRagMemoryService 또는 기타 BaseMemoryService 구현과 같은 두 번째 서비스를 수동으로 인스턴스화할 수 있습니다.
예: 두 개의 메모리 서비스 사용¶
from google.adk.agents import Agent
from google.adk.memory import InMemoryMemoryService
from google.adk.tools import ToolContext
# Second memory service for docs lookup; could be any BaseMemoryService.
docs_memory = InMemoryMemoryService()
async def search_all_memory(query: str, tool_context: ToolContext) -> dict:
"""Search both the conversational memory and the docs corpus."""
conversational = await tool_context.search_memory(query)
docs = await docs_memory.search_memory(
app_name="docs", user_id="shared", query=query
)
return {
"from_conversations": [
part.text
for entry in conversational.memories
for part in (entry.content.parts or [])
if part.text
],
"from_docs": [
part.text
for entry in docs.memories
for part in (entry.content.parts or [])
if part.text
],
}
agent = Agent(
model="gemini-flash-latest",
name="multi_memory_agent",
instruction=(
"Answer questions using both your conversation history and the "
"docs knowledge base. Use the search_all_memory tool."
),
tools=[search_all_memory],
)
/**
* Example of using two memory services in Kotlin.
*/
suspend fun searchAllMemory(
toolContext: ToolContext,
query: String,
docsMemory: InMemoryMemoryService,
): Map<String, List<String>> {
// Search the conversational memory (configured in the runner)
val conversational =
toolContext.invocationContext.memoryService?.searchMemory(
appName = toolContext.invocationContext.session.key.appName,
userId = toolContext.invocationContext.session.key.userId,
query = query,
)
// Search a separate docs knowledge base
val docs =
docsMemory.searchMemory(
appName = "docs",
userId = "shared",
query = query,
)
return mapOf(
"from_conversations" to
(
conversational?.memories?.map {
it.content.parts.joinToString(" ") { p -> p.text ?: "" }
} ?: emptyList()
),
"from_docs" to
docs.memories.map {
it.content.parts.joinToString(" ") { p -> p.text ?: "" }
},
)
}
fun multiMemoryAgent(model: Gemini) {
// docs_memory could be any MemoryService implementation
val docsMemory = InMemoryMemoryService()
val agent =
LlmAgent(
model = model,
name = "multi_memory_agent",
instruction =
Instruction(
"Answer questions using both your conversation history and the " +
"docs knowledge base. Use the search_all_memory tool.",
),
// In a real app, you'd wrap searchAllMemory in a @Tool annotated class
// and pass docsMemory to its constructor.
)
}