Agent Platform SDK for Python: 버전 2.0.1 마이그레이션 가이드

google-cloud-aiplatform 패키지에는 Python용 Agent Platform SDK와 Agent Platform Python 클라이언트 라이브러리가 모두 포함되어 있습니다. 이 페이지에서는 google-cloud-aiplatform 패키지의 다음과 같은 변경사항 카테고리를 다룹니다.

  • 생성형 AI 모듈이 Google 생성형 AI SDK로 이동: vertexai 패키지의 다음 생성형 AI 모듈이 지원 중단되고 Google 생성형 AI SDK (google-genai)로 마이그레이션됩니다.

    • vertexai.generative_models
    • vertexai.language_models
    • vertexai.vision_models
    • vertexai.caching
    • vertexai.tuning

    지원 중단된 모듈을 Google 생성형 AI SDK로 마이그레이션하는 방법은 생성형 AI 모듈을 Google 생성형 AI SDK로 이전을 참고하세요.

  • 에이전트 표시 경로 재구성: google-cloud-aiplatform의 agentplatform 모듈이 다음과 같이 변경되었습니다.

    • 이름 바꾸기
    • 최상위 수준으로 승격
    • 전역 이니셜라이저 삭제

    새 SDK 구조로 이전하는 방법을 알아보려면 Agent Platform SDK 재구성을 참고하세요.

  • agentplatform 분리: 이제 google-cloud-agentplatform는 독립형 경량 배포판이며 에이전트 워크로드에 권장되는 설치입니다. 에이전트만 빌드하는 경우 생성형 AI 모듈이 포함되지 않은 google-cloud-agentplatform를 설치합니다. agentplatform 모듈은 [adk], [a2a], [agent_engines], [langchain], [ag2], [llama_index], [evaluation], [bigquery], [live], [all]와 같은 일반적인 통합을 다룹니다.

영향을 받지 않는 항목

기존 머신러닝 표면 (데이터 세트, 학습, 모델, 예측, 추적, 파이프라인)은 완전히 지원되며 버전 2.0.1 변경사항의 영향을 받지 않으며 Google 생성형 AI SDK에는 이에 상응하는 기능이 없습니다. google-cloud-aiplatform를 설치하면 평가, Agent Runtime, 프롬프트, 스킬에 계속 액세스할 수 있습니다. google-cloud-aiplatform 및 google-genai는 모두 한 환경에 공존하며 이제 google-genai는 google-cloud-aiplatform의 하드 종속 항목입니다.

import agentplatform

client = agentplatform.Client(project="my-project", location="global")
# client.evals                  client.prompts
# client.prompt_optimizer client.datasets           client.skills

vertexai.batch_prediction는 지원 중단되지 않았지만 Google 생성형 AI SDK에 상응하는 도구가 있으며 권장되는 도구입니다.

생성형 AI 모듈을 Google 생성형 AI SDK로 이전

google-cloud-aiplatform 패키지의 생성형 AI 모듈을 사용하는 경우 다음 권장사항을 사용하여 Google 생성형 AI SDK (google-genai)로 마이그레이션하세요.

  1. 관련 없는 종속 항목 범프가 아래의 모듈을 삭제할 수 없도록 google-cloud-aiplatform < 2.0.0를 설정합니다.

  2. 코드에서 지원 중단된 모듈을 검색합니다.

    • vertexai.generative_models
    • vertexai.language_models
    • vertexai.vision_models
    • vertexai.caching
    • vertexai.tuning

    영향을 받는 Python 모듈을 가져오면 다음 지원 중단 경고가 표시됩니다.

    UserWarning: This feature is deprecated as of June 24, 2025 and will be removed on
June 24, 2026. For details, see
https://cloud.google.com/vertex-ai/generative-ai/docs/deprecations/genai-vertexai-sdk.

    -W error::UserWarning로 테스트 모음을 실행하여 누락된 가져오기를 포착합니다.

  3. vertexai.init(...)을 명시적 genai.Client(enterprise=True, project=..., location=...)로 바꿉니다. 기존 머신러닝 표면도 사용하는 경우 vertexai.init()를 유지합니다.

    이전 

    # pip install google-cloud-aiplatform

import vertexai
from vertexai.generative_models import GenerativeModel

vertexai.init(project="my-project", location="us-central1")

# Model identity and config are bound at construction time.
model = GenerativeModel("gemini-2.5-flash")

    이후 

    # pip install google-genai

from google import genai
from google.genai import types

client = genai.Client(
    enterprise=True,
    project="my-project",
    location="global",
)

    또는 환경에서 구성합니다.

    export GOOGLE_GENAI_USE_ENTERPRISE=true
export GOOGLE_CLOUD_PROJECT=my-project
export GOOGLE_CLOUD_LOCATION=global

    from google import genai

client = genai.Client()

    주요 고려사항:

    • 전역 상태가 명시적 클라이언트가 됩니다. vertexai.init()는 전체 프로세스를 구성하고 genai.Client()는 전달하는 객체입니다. genai.Client()를 사용하면 한 프로세스에서 두 개의 프로젝트 또는 리전을 사용할 수 있습니다.
    • enterprise=True 필드는 필수 항목입니다. 생략하면 클라이언트가 Gemini Developer API를 자동으로 타겟팅하며, 이 경우 애플리케이션 기본 사용자 인증 정보에서 실패하거나 API 키를 요구합니다.
    • 모델 이름이 구성에서 모든 호출로 이동합니다. 한 번 결합 모델 객체가 없습니다. model=는 각 client.models.* 호출의 필수 키워드 인수입니다.
    • 인증은 변경되지 않습니다. 애플리케이션 기본 사용자 인증 정보는 계속 적용되며 credentials=는 두 SDK에서 모두 google.auth.credentials.Credentials를 허용합니다.
    • vertexai.init()에는 staging_bucket, experiment, encryption_spec_key_name, service_account, network와 같은 비생성 설정도 포함되어 있었습니다. genai.Client에는 이에 상응하는 기능이 없습니다.
    • 최신 enterprise=True 철자는 google-genai 2.20.0부터 허용되지만 이전 버전 vertexai=True는 모든 출시 버전에서 작동하며 더 안전한 선택입니다.

  4. 오류 없이 동작이 달라지는 자동 변경사항이 있는지 코드를 검사합니다. 컴파일 및 실행되지만 의미가 변경됩니다.

    동작 이전 이후
    차단되거나 비어 있는 대답에 대한 response.text ValueError 증가 반환 값 None
    여러 후보가 있는 response.text ValueError 증가 경고를 로깅하고 첫 번째 후보를 반환합니다.
    고객 타겟팅 vertexai.init() 암시적 Agent Platform vertexai=True를 생략하면 Gemini Developer API가 자동으로 타겟팅됩니다.
    임베딩 auto_truncate 기본값은 True입니다. 설정 해제, 서버 기본값 적용
    도구로 전달된 Python 함수 지원되지 않음 SDK에서 자동으로 실행됨
    system_instruction 모델에 한 번 바인딩됨 모든 호출에서 전달되어야 함

    response.text 변경사항을 먼저 검색해야 합니다. .text를 감싸는 모든 try/except ValueError는 데드 코드가 되고, 보호되지 않은 모든 .text는 이제 이전에 str가 반환된 None를 생성할 수 있습니다.

    if response.text is None:
    print(
        "blocked or empty:",
        response.prompt_feedback,
        response.candidates[0].finish_reason if response.candidates else None,
    )

  5. 평가, Agent Runtime, 프롬프트, 데이터 세트, 기술, 전체 기존 머신러닝 표면을 사용하는 경우 google-cloud-aiplatform를 설치된 상태로 유지합니다.

  6. 새 버전으로 호출을 변경합니다. 기계적 이름 바꾸기부터 시작한 다음 config= 통합을 진행합니다.

작업 기반 통화 변경사항

작업에 따라 변경된 호출을 확인합니다.

텍스트 생성

텍스트 생성 작업의 경우 모든 인수가 키워드 전용입니다. 위치 호출은 TypeError를 발생시킵니다.

이전 

model = GenerativeModel("gemini-2.5-flash")

response = model.generate_content("Why is the sky blue?")
print(response.text)

이후 

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Why is the sky blue?",
)
print(response.text)

스트리밍 생성

스트리밍 생성 작업의 경우 stream=True 플래그가 삭제됩니다. 이제 스트리밍은 Iterator[types.GenerateContentResponse]를 반환하는 별도의 메서드입니다. 각 청크는 전체 응답 객체이며 .text 속성이 None인 경우가 있으므로 텍스트에 액세스하기 전에 if chunk.text:를 사용하여 확인하세요.

이전 

stream = model.generate_content("Tell me a story in 300 words.", stream=True)
for chunk in stream:
    print(chunk.text, end="")

이후 

for chunk in client.models.generate_content_stream(
    model="gemini-3.5-flash",
    contents="Tell me a story in 300 words.",
):
    if chunk.text:
        print(chunk.text, end="")

비동기 생성

비동기 생성 작업의 경우 _async 메서드 이름 서픽스가 삭제되었습니다. 모든 비동기 호출은 동기 호출과 동일한 메서드 이름으로 client.aio.<module> 아래에 있습니다. await client.aio.aclose()를 사용하여 클라이언트를 닫거나 async with genai.Client(...).aio as aclient:를 사용합니다.

이전 

response = await model.generate_content_async("Why is the sky blue?")

async_stream = await model.generate_content_async("Why is the sky blue?", stream=True)
async for chunk in async_stream:
    print(chunk.text, end="")

이후 

response = await client.aio.models.generate_content(
    model="gemini-3.5-flash",
    contents="Why is the sky blue?",
)

# Note the `await` in front of the async iterator.
async for chunk in await client.aio.models.generate_content_stream(
    model="gemini-3.5-flash",
    contents="Tell me a story in 300 words.",
):
    print(chunk.text, end="")

채팅 세션

채팅 세션 작업에 대한 다음 변경사항에 유의하세요.

  • 채팅은 모델 객체가 아닌 클라이언트에서 생성됩니다.
  • chat.history (속성)가 chat.get_history() (메서드)가 됩니다. 새 메서드는 curated: bool = False를 사용합니다. True를 전달하면 유지된 차례만 반환되며, 이전 버전에는 이에 상응하는 항목이 없습니다.
  • client.aio.chats.create(...)는 AsyncChat를 직접 반환합니다. send_message 및 send_message_stream만 대기 중입니다.
  • 턴별 옵션은 하나의 인수(send_message(message, config=types.GenerateContentConfig(...)))로 축소됩니다. 첫 번째 매개변수도 content에서 message로 이름이 변경되었습니다.

  • start_chat(response_validation=False)는 이전 버전과 동일한 기능이 없는 새로운 메서드입니다.

이전 

model = GenerativeModel("gemini-2.5-flash")
chat = model.start_chat()

print(chat.send_message("Tell me a story").text)

for content in chat.history:
    print(content.role, content.parts)

이후 

chat = client.chats.create(model="gemini-3.5-flash")

print(chat.send_message("Tell me a story").text)

for content in chat.get_history():
    print(content.role, content.parts)

구성, 안전 설정, 시스템 안내

구성, 안전 설정, 시스템 요청 사항 작업에 대한 다음 변경사항에 유의하세요.

  • 다음 인수는 GenerateContentConfig의 필드로 하나의 config=로 축소됩니다.

    • generation_config
    • safety_settings
    • tools
    • tool_config
    • labels
    • system_instruction

    일반 dict는 구성 유형이 작동하는 모든 위치에서 작동합니다.

  • system_instruction가 모델 생성자에서 호출별 구성으로 이동합니다. 이전 SDK 버전에서는 GenerativeModel를 빌드할 때 system_instruction가 한 번 설정되었습니다. 이제 system_instruction를 모든 호출에 전달하거나 client.chats.create(config=...)에 포함해야 합니다.

  • 안전 설정이 dict에서 list로 변경됩니다. 예를 들면 [types.SafetySetting(category=c, threshold=t) for c, t in old_dict.items()]입니다.

  • enum은 일반 문자열로 허용되고 강제 변환됩니다.

  • 스칼라 필드 이름은 변경되지 않습니다(temperature, top_p, top_k, candidate_count, max_output_tokens, stop_sequences, presence_penalty, frequency_penalty, seed, response_mime_type, response_schema, response_logprobs, logprobs).

  • 이전 필드와 동일하지 않은 새 필드에는 thinking_config, cached_content, automatic_function_calling, http_options, media_resolution, speech_config가 포함됩니다.

이전 

from vertexai.generative_models import (
    GenerativeModel, GenerationConfig, HarmCategory, HarmBlockThreshold,
)

model = GenerativeModel(
    "gemini-2.5-flash",
    system_instruction=["Talk like a pirate.", "Don't use rude words."],
)

response = model.generate_content(
    contents="Why is the sky blue?",
    generation_config=GenerationConfig(temperature=0, top_p=0.95, max_output_tokens=100),
    safety_settings={
        HarmCategory.HARM_CATEGORY_HATE_SPEECH: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
        HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT: HarmBlockThreshold.BLOCK_ONLY_HIGH,
    },
)

이후 

from google.genai import types

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Why is the sky blue?",
    config=types.GenerateContentConfig(
      system_instruction="Talk like a pirate. Don't use rude words.",
      temperature=0,
      top_p=0.95,
      max_output_tokens=100,
      safety_settings=[
          types.SafetySetting(
              category="HARM_CATEGORY_HATE_SPEECH",
              threshold="BLOCK_MEDIUM_AND_ABOVE",
          ),
          types.SafetySetting(
              category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
              threshold=types.HarmBlockThreshold.BLOCK_ONLY_HIGH,
          ),
      ],
    ),
)

멀티모달 입력하기

멀티모달 입력 작업의 경우 다음 변경사항에 유의하세요.

이전 오퍼 신규
Part.from_uri(uri, mime_type), 위치 허용됨 Part.from_uri(file_uri=, mime_type=), 키워드 전용, 매개변수 이름이 변경됨
Part.from_data(data, mime_type) Part.from_bytes(data=, mime_type=), 메서드 이름 변경됨
Part.from_text(text) Part.from_text(text=), 키워드 전용
Image.load_from_file(path) 해당 없음. 파일을 열고 Part.from_bytes 사용
  • mime_type는 types.Part.from_uri()에서 선택사항이지만(서버 측에서 추론됨) types.Part.from_bytes()에서는 필수입니다.

  • client.files.upload(...)는 Gemini Developer API에서만 지원됩니다. Agent Platform 워크로드의 경우 from_uri를 사용하여 Cloud Storage URI를 전달하거나 from_bytes를 사용하여 인라인 바이트를 전달합니다.

이전 

from vertexai.generative_models import GenerativeModel, Part, Image

image = Image.load_from_file("image.jpg")
print(model.generate_content(["What is shown in this image?", image]).text)

image_part = Part.from_uri(
    "gs://cloud-samples-data/generative-ai/image/scones.jpg",
    mime_type="image/jpeg",
)

이후 

from google.genai import types

# Image.load_from_file has no equivalent: read the bytes yourself.
with open("image.jpg", "rb") as f:
    image = types.Part.from_bytes(data=f.read(), mime_type="image/jpeg")

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=["What is shown in this image?", image],
)

image_part = types.Part.from_uri(
    file_uri="gs://cloud-samples-data/generative-ai/image/scones.jpg",
    mime_type="image/jpeg",
)

함수 호출 및 그라운딩

함수 호출 및 그라운딩 작업의 다음 변경사항에 유의하세요.

  • 도구가 config=로 이동합니다. 호출 또는 모델 객체에 tools= 인수가 없습니다.
  • Tool.from_google_search_retrieval(grounding.GoogleSearchRetrieval())가 types.Tool(google_search=types.GoogleSearch())가 됩니다. 팩토리 메서드가 일반 필드가 됩니다. types.Tool에는 별도의 google_search_retrieval 필드도 있습니다.
  • response.function_calls는 관용적 접근자이며 파트 0이 텍스트인 경우 실패하지 않습니다. 이전 순회는 계속 작동합니다.
  • 원시 JSON 스키마는 parameters_json_schema에 지정됩니다. 유형이 지정된 types.Schema는 parameters에 지정됩니다.
  • 이제 Python 함수를 도구로 전달할 수 있으며, 함수를 전달하면 자동 함수 호출이 기본적으로 사용 설정됩니다. 수동 도구 루프를 포팅하고 함수 객체를 전달하면 SDK가 코드 실행을 시작합니다. automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True)를 사용하여 기본 자동 함수 호출을 사용 중지합니다.

  • 다음과 같은 새로운 도구 유형은 이전 버전에서 상응하는 도구가 없습니다. code_execution, url_context, google_maps, computer_use, file_search, enterprise_web_search, mcp_servers

이전 

from vertexai.generative_models import GenerativeModel, FunctionDeclaration, Tool, grounding

weather_tool = Tool(function_declarations=[
    FunctionDeclaration(
        name="get_current_weather",
        description="Get the current weather in a given location",
        parameters={
            "type": "object",
            "properties": {"location": {"type": "string"}},
            "required": ["location"],
        },
    )
])

model = GenerativeModel("gemini-2.5-flash", tools=[weather_tool])
response = model.generate_content("What is the weather in Boston?")
call = response.candidates[0].content.parts[0].function_call

# Grounding
search_tool = Tool.from_google_search_retrieval(grounding.GoogleSearchRetrieval())

이후 

from google.genai import types

weather_tool = types.Tool(function_declarations=[
    types.FunctionDeclaration(
        name="get_current_weather",
        description="Get the current weather in a given location",
        parameters_json_schema={
            "type": "object",
            "properties": {"location": {"type": "string"}},
            "required": ["location"],
        },
    )
])

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="What is the weather in Boston?",
    config=types.GenerateContentConfig(tools=[weather_tool]),
)
call = response.function_calls[0]

# Grounding
search_tool = types.Tool(google_search=types.GoogleSearch())

임베딩

임베딩 작업의 다음 변경사항에 유의하세요.

  • TextEmbeddingInput가 삭제되었습니다. task_type 및 title는 이제 요청별로 처리되므로 혼합 작업 배치는 여러 호출로 분할해야 합니다.
  • 반환 유형이 직접 목록에서 응답 객체로 변경되었습니다. get_embeddings()는 list[TextEmbedding]를 직접 반환하므로 호출자가 목록의 색인을 직접 생성했습니다 (embeddings[0].values). 새 버전에서 embed_content()는 .embeddings 목록이 포함된 EmbedContentResponse 객체를 반환하므로 response.embeddings[0].values에 액세스해야 합니다. 개별 임베딩 필드 (.values 및 .statistics)는 원래 이름을 유지합니다.

  • auto_truncate의 기본값이 더 이상 True가 아닙니다. 새 필드의 기본값은 unset입니다. 너무 긴 입력을 자동으로 자르는 경우 auto_truncate를 명시적으로 설정합니다.

이전 

from vertexai.language_models import TextEmbeddingModel, TextEmbeddingInput

model = TextEmbeddingModel.from_pretrained("gemini-embedding-001")

text_input = TextEmbeddingInput(
    text="How do I get a driver's license?",
    task_type="RETRIEVAL_DOCUMENT",   # per input
    title="Driver's License",         # per input
)

embeddings = model.get_embeddings([text_input], output_dimensionality=3072, auto_truncate=True)
print(embeddings[0].values)

이후 

from google.genai import types

response = client.models.embed_content(
    model="gemini-embedding-2",
    contents="How do I get a driver's license?",
    config=types.EmbedContentConfig(
        task_type="RETRIEVAL_DOCUMENT",   # now per request
        title="Driver's License",         # now per request
        output_dimensionality=3072,
        auto_truncate=True,
    ),
)
print(response.embeddings[0].values)

토큰 수 계산

토큰 계산 작업의 다음 변경사항에 유의하세요.

  • total_billable_characters가 삭제되었으며 대체 항목이 없습니다. total_billable_characters를 키로 하는 모든 비용 추정은 생성 호출에서 다시 작업해야 합니다 (예: total_tokens 또는 response.usage_metadata).
  • 토큰 ID 및 문자열 조각에 client.models.compute_tokens(...)가 추가되었습니다.

  • google.genai.local_tokenizer.LocalTokenizer를 통해 오프라인 집계가 추가되었습니다.

이전 

model = GenerativeModel("gemini-2.5-flash")

response = model.count_tokens(["Why is the sky blue?"])
print(response.total_tokens)
print(response.total_billable_characters)

이후 

response = client.models.count_tokens(
    model="gemini-3.5-flash",
    contents=["Why is the sky blue?"],
)
print(response.total_tokens)
print(response.cached_content_token_count)

컨텍스트 캐싱이

컨텍스트 캐싱 작업의 경우 다음 변경사항에 유의하세요.

  • ttl는 유형을 datetime.timedelta에서 "86400s"와 같은 기간 문자열로 변경합니다.
  • 리소스 객체 메서드는 클라이언트 모듈 호출이 됩니다.

  • update는 제자리에서 변경하는 대신 새 객체를 반환합니다.

이전 

import datetime
from vertexai.caching import CachedContent

cache = CachedContent.create(
    model_name="gemini-2.5-flash",
    system_instruction="Please answer my question formally",
    contents=contents,
    ttl=datetime.timedelta(days=1),
)
cache.update(ttl=datetime.timedelta(days=2))
cache.delete()

이후 

from google.genai import types

cache = client.caches.create(
    model="gemini-3.5-flash",
    config=types.CreateCachedContentConfig(
        contents=contents,
        system_instruction="Please answer my question formally",
        ttl="86400s",
    ),
)
cache = client.caches.update(
    name=cache.name, config=types.UpdateCachedContentConfig(ttl="172800s")
)
client.caches.delete(name=cache.name)

일괄 예측 및 조정

일괄 예측 및 조정 작업의 다음 변경사항에 유의하세요.

  • 폴링은 인플레이스가 아닌 리바인드 기반입니다. job.refresh() 및 job.has_ended가 없습니다. client.batches.get(name=...)에서 새 객체를 가져와 job.state를 JOB_STATE_* 문자열과 비교합니다.
  • 일괄 이름 변경: source_model에서 model로, input_dataset에서 src로, output_uri_prefix에서 config.dest로, job_display_name에서 config.display_name로 변경되었습니다.
  • 일괄 머신 형태 컨트롤이 삭제되었으며 새 SDK 버전에는 이에 상응하는 컨트롤이 없습니다. machine_type, accelerator_type, accelerator_count, starting_replica_count, max_replica_count는 더 이상 CreateBatchJobConfig의 필드가 아닙니다.
  • 다음 메서드의 이름이 변경되었습니다.
    • sft.train~client.tunings.tune
    • source_model~base_model
    • train_dataset~training_dataset
    • epochs~epoch_count
  • 조정 데이터 세트가 래핑됩니다. 일반 "gs://..." 문자열은 types.TuningDataset(gcs_uri=...)가 됩니다.

  • adapter_size의 유형이 int에서 enum 문자열(예: "ADAPTER_SIZE_FOUR")로 변경됩니다.

이전 

from vertexai.batch_prediction import BatchPredictionJob
from vertexai.tuning import sft

job = BatchPredictionJob.submit(
    source_model="gemini-2.5-flash",
    input_dataset="bq://my-project.my-dataset.my-table",
    output_uri_prefix="bq://my-project.my-dataset.output",
)
while not job.has_ended:
    job.refresh()

tuning_job = sft.train(
    source_model="gemini-2.5-flash",
    train_dataset="gs://bucket/train.jsonl",
    epochs=1,
    adapter_size=4,
)

이후 

from google.genai import types

job = client.batches.create(
    model="gemini-3.5-flash",
    src="bq://my-project.my-dataset.my-table",
    config=types.CreateBatchJobConfig(dest="bq://my-project.my-dataset.output"),
)
completed = {"JOB_STATE_SUCCEEDED", "JOB_STATE_FAILED", "JOB_STATE_CANCELLED", "JOB_STATE_PAUSED"}
while job.state not in completed:
    job = client.batches.get(name=job.name)

tuning_job = client.tunings.tune(
    base_model="gemini-3.5-flash",
    training_dataset=types.TuningDataset(gcs_uri="gs://bucket/train.jsonl"),
    config=types.CreateTuningJobConfig(
        epoch_count=1,
        adapter_size="ADAPTER_SIZE_FOUR",
    ),
)

Agent Platform SDK 재구성

google-cloud-aiplatform의 agentplatform 모듈을 사용하는 경우 다음 권장사항을 사용하여 새 SDK 구조로 이전하세요.

  1. 이제 google-cloud-agentplatform는 독립형 경량 배포판이며 에이전트 워크로드에 권장되는 설치입니다. 기존 머신러닝 표면이 필요하지 않은 경우 설치를 pip install google-cloud-aiplatform에서 pip install google-cloud-agentplatform로 전환합니다.

  2. 다음 표를 사용하여 가져오기 및 속성 경로를 업데이트합니다.

    이전 신규
    client.agent_engines.create client.runtimes.create (기본 제공 Agent Platform 세션, 샌드박스 코드 실행, 컨텍스트 메모리 구성을 제공하는 Gemini Enterprise Agent Platform 인스턴스에 Agent Runtime 배포)
    client.memory_banks.create (상호작용 전반에서 메모리를 유지, 관리, 검색하기 위한 독립형 Agent Platform 메모리 뱅크 리소스 만들기)
    client.agent_engines.sandboxes client.sandboxes
    client.agent_engines.sandboxes.snapshots client.sandboxes.snapshots
    client.agent_engines.sandboxes.templates client.sandboxes.templates
    client.agent_engines.sessions client.sessions
    client.agent_engines.sessions.events client.sessions.events
    client.agent_engines.runtimes.revisions client.runtimes.revisions
    client.agent_engines.memories client.memory_banks.memories
    agentplatform.agent_engines.templates agentplatform.frameworks

  3. 전역 이니셜라이저가 삭제되고 에이전트 프레임워크가 더 이상 aiplatform.init() 또는 vertexai.init() 상태에서 프로젝트 및 위치를 읽지 않습니다. 에이전트 프레임워크 내에서 실행되는 모든 항목에 대해 이니셜라이저에서 파생된 구성을 환경 변수로 바꿉니다. 이니셜라이저를 사용하여 배포된 에이전트를 구성하는 코드는 오류를 발생시키지 않고 자동으로 중단됩니다.

  4. SDK에서 더 이상 types.AgentEngine를 허용하지 않으므로 types.Runtime를 전달하도록 evals.run_inference(agent=...) 호출 사이트를 업데이트합니다.

  5. 다음과 같이 변경하세요.

    • vertexai.Client~agentplatform.Client
    • vertexai.rag~agentplatform.Client().rag

    vertexai.Client는 첫 번째 인스턴스화에서 FutureWarning를 내보냅니다.

    The vertexai.Client class is deprecated. Please use agentplatform.Client instead.

    vertexai.rag는 호출 시가 아닌 모듈 가져오기 시 UserWarning를 내보냅니다. 다음으로 이전합니다.

    import agentplatform

client = agentplatform.Client(project="your-project", location="global")
client.rag.create_corpus(...)

  6. AdkApp 및 세션 호출 관련 오류 처리를 업데이트합니다. 이제 동기 세션 메서드와 스트리밍 에이전트 실행에서 기본 API 오류가 표시됩니다. 일반 래핑된 오류를 포착하는 호출자는 더 이상 일치하지 않습니다. 일반 라이브러리 래퍼 예외의 catch를 google.api_core.exceptions.GoogleAPICallError (또는 ResourceExhausted 및 NotFound과 같은 특정 상태 오류)로 바꿉니다.

  7. 이제 토큰은 일시적이며 세션 상태와 함께 유지되지 않으므로 각 요청에 사용자의 OAuth 액세스 토큰을 포함하도록 클라이언트 호출자 또는 미들웨어를 업데이트합니다. 토큰 새로고침이 클라이언트 측에서 관리되는지 확인합니다.

  8. a2a.tasks 모듈은 대체 없이 삭제되었습니다.