Vertex AI Agent Engine SDK 빠른 시작

이 튜토리얼에서는 Vertex AI Agent Engine SDK를 사용하여 Vertex AI Agent Engine의 세션 및 메모리 뱅크에 직접 API를 호출하는 방법을 보여줍니다. 에이전트 프레임워크가 호출을 대신 조정하지 않기를 원하거나 에이전트 개발 키트(ADK) 이외의 다른 에이전트 프레임워크와 세션 및 메모리 뱅크를 통합하려는 경우 Vertex AI Agent Engine SDK를 사용하세요.

ADK를 사용하는 빠른 시작은 에이전트 개발 키트 빠른 시작을 참조하세요.

이 튜토리얼은 다음 단계를 다룹니다.

  1. 다음 옵션을 사용하여 메모리를 만듭니다.
  2. 메모리를 검색합니다.
  3. 삭제합니다.

시작하기 전에

이 튜토리얼에 설명된 단계를 완료하려면 먼저 메모리 뱅크 설정의 단계를 수행해야 합니다.

Vertex AI Agent Engine 세션으로 메모리 생성

Vertex AI Agent Engine 세션 및 메모리 뱅크를 설정한 후 세션을 만들고 이벤트를 추가할 수 있습니다. 메모리는 사용자가 에이전트와 나눈 대화에서 사실(fact)로 생성되며, 이후 사용자 상호작용에서 활용할 수 있습니다. 자세한 내용은 메모리 생성 및 메모리 가져오기를 참조하세요.

  1. 불투명 사용자 ID로 세션을 만듭니다. 이 세션에서 생성된 메모리는 메모리를 생성할 때 범위를 명시적으로 제공하지 않는 한 범위 {"user_id": "USER_ID"}를 사용하여 자동으로 키가 지정됩니다.

    import vertexai

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION"
)

session = client.agent_engines.sessions.create(
  name=AGENT_ENGINE_NAME,
  user_id="USER_ID"
)

    다음을 바꿉니다.

    • PROJECT_ID: 프로젝트 ID입니다.

    • LOCATION: 리전입니다. 메모리 뱅크에서 지원되는 리전을 참조하세요.

    • AGENT_ENGINE_NAME: 사용자가 만든 Vertex AI Agent Engine 인스턴스 또는 기존 Vertex AI Agent Engine 인스턴스 이름입니다. 이름 형식은 다음과 같아야 합니다: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.

    • USER_ID: 사용자의 식별자. 이 세션에서 생성된 메모리는 메모리를 생성할 때 범위를 명시적으로 제공하지 않는 한 범위 {"user_id": "USER_ID"}를 사용하여 자동으로 키가 지정됩니다.

  2. 세션에 이벤트를 반복적으로 업로드합니다. 이벤트에는 사용자, 에이전트, 도구 간의 모든 상호작용이 포함될 수 있습니다. 순서가 지정된 이벤트 목록은 세션의 대화 기록을 나타냅니다. 이 대화 기록은 특정 사용자의 메모리를 생성하기 위한 소스 자료로 사용됩니다.

    import datetime

client.agent_engines.sessions.events.append(
  name=session.response.name,
  author="user",  # Required by Sessions.
  invocation_id="1",  # Required by Sessions.
  timestamp=datetime.datetime.now(tz=datetime.timezone.utc),  # Required by Sessions.
  config={
    "content": {
      "role": "user",
      "parts": [{"text": "hello"}]
    }
  }
)

  3. 대화 기록에서 메모리를 생성하려면 세션의 메모리 생성 요청을 트리거합니다.

    client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source={
    # `session` should have the format "projects/.../locations/.../reasoningEngines/.../sessions/...".
    "session": session.response.name
  },
  # Optional when using Agent Engine Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE
)

다음을 바꿉니다.

  • (선택사항) SCOPE: 생성된 메모리의 범위를 나타내는 사전으로, 키-값 쌍은 최대 5개까지 허용되며 * 문자는 허용되지 않습니다. 예를 들면 {"session_id": "MY_SESSION"}입니다. 동일한 범위의 메모리만 통합 대상으로 간주됩니다. 입력하지 않으면 {"user_id": session.user_id}가 사용됩니다.

메모리 업로드

원시 대화로부터 메모리를 생성하는 대신, 사전 추출된 사실을 활용해서 메모리를 직접 업로드하거나 에이전트가 GenerateMemories를 사용해 추가하도록 할 수 있습니다. 즉, 메모리 뱅크가 콘텐츠에서 정보를 추출하는 대신 사용자가 보존해야 할 사실을 직접 제공하는 방식입니다. 사용자에 대한 사실은 1인칭으로 작성하는 것이 좋습니다(예: I am a software engineer).

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

다음을 바꿉니다.

  • FACT: 기존 메모리와 통합해야 하는 사전 추출된 사실(fact)입니다. 최대 5개의 사전 추출된 사실(fact)을 목록으로 제공할 수 있습니다.

    {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}

  • SCOPE: 생성된 메모리의 범위를 나타내는 사전입니다. 예를 들면 {"session_id": "MY_SESSION"}입니다. 동일한 범위의 메모리만 통합 대상으로 간주됩니다.

또는 CreateMemory를 사용하여 메모리 뱅크의 추출이나 통합을 거치지 않고 메모리를 업로드할 수도 있습니다.

memory = client.agent_engines.memories.create(
    name=agent_engine.api_resource.name,
    fact="This is a fact.",
    scope={"user_id": "123"}
)

"""
Returns an AgentEngineMemoryOperation containing the created Memory like:

AgentEngineMemoryOperation(
  done=True,
  metadata={
    "@type': 'type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateMemoryOperationMetadata",
    "genericMetadata": {
      "createTime": '2025-06-26T01:15:29.027360Z',
      "updateTime": '2025-06-26T01:15:29.027360Z'
    }
  },
  name="projects/.../locations/us-central1/reasoningEngines/.../memories/.../operations/...",
  response=Memory(
    create_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC)),
    fact="This is a fact.",
    name="projects/.../locations/us-central1/reasoningEngines/.../memories/...",
    scope={
      "user_id": "123"
    },
    update_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC))
  )
)
"""

메모리 검색 및 사용

사용자에 대한 메모리를 검색하여 시스템 지침에 포함시킴으로써 LLM이 맞춤설정된 컨텍스트에 액세스하도록 할 수 있습니다.

범위 기반 메서드를 사용해 메모리를 검색하는 방법에 대한 자세한 내용은 메모리 가져오기를 참조하세요.

# Retrieve all memories for User ID 123.
retrieved_memories = list(
    client.agent_engines.memories.retrieve(
        name=agent_engine.api_resource.name,
        scope={"user_id": "123"}
    )
)

구조화된 메모리를 프롬프트로 변환하기 위해 jinja를 사용할 수 있습니다.


from jinja2 import Template

template = Template("""
<MEMORIES>
Here is some information about the user:
{% for retrieved_memory in data %}* {{ retrieved_memory.memory.fact }}
{% endfor %}</MEMORIES>
""")

prompt = template.render(data=retrieved_memories)

"""
Output:

<MEMORIES>
Here is some information about the user:
* This is a fact
</MEMORIES>
"""

메모리 삭제

특정 메모리는 해당 리소스 이름을 사용하여 삭제할 수 있습니다.

client.agent_engines.memories.delete(name=MEMORY_NAME)

다음을 바꿉니다.

  • MEMORY_NAME: 삭제할 메모리의 이름입니다. 이름 형식은 다음과 같아야 합니다: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}. 메모리 이름은 메모리를 가져오는 과정에서 확인할 수 있습니다.

삭제

이 프로젝트에 사용된 모든 리소스를 삭제하려면 빠른 시작에 사용한 Google Cloud 프로젝트를 삭제하면 됩니다.

또는 다음과 같이 이 튜토리얼에서 만든 개별 리소스를 삭제하면 됩니다.

  1. 다음 코드 샘플을 사용하여 Vertex AI Agent Engine 인스턴스를 삭제합니다. 그러면 Vertex AI Agent Engine 인스턴스와 연결된 모든 세션 또는 메모리도 삭제됩니다.

    agent_engine.delete(force=True)

  2. 로컬에서 만든 파일을 삭제합니다.

다음 단계