에이전트 애플리케이션 만들기

이 가이드에서는 날씨에 관한 사용자 질문에 답변할 수 있는 기본적인 에이전트 애플리케이션을 만드는 단계를 안내합니다.

시작하기 전에

이 가이드를 따르기 전에 설정 안내를 완료해야 합니다.

에이전트 애플리케이션 만들기

에이전트 애플리케이션과 루트 에이전트를 만듭니다.

  1. Gemini Enterprise for CX 콘솔을 엽니다.
  2. 프로젝트를 선택합니다.
  3. 에이전트 만들기 또는 새 에이전트를 클릭합니다.
  4. 에이전트 이름으로 'weather app'을 입력합니다.
  5. 만들기를 클릭합니다. 프로젝트에 대해 만든 첫 번째 에이전트 애플리케이션인 경우 만드는 데 1~2분 정도 걸릴 수 있습니다. 에이전트 빌더가 표시되고 루트 에이전트가 생성됩니다.

에이전트 계층 구조 만들기

이 에이전트 애플리케이션은 다음 세 가지 에이전트를 사용합니다.

  • 사용자에게 인사하고 다른 하위 에이전트에게 위임하는 루트 에이전트
  • 날씨 관련 질문에 답변하는 날씨 에이전트
  • 대화를 완료하려면 'Farewell'이라고 입력하세요.

루트 에이전트는 이미 생성되었지만 이 에이전트의 설정을 업데이트해야 합니다.

  1. 루트 에이전트의 제목 표시줄을 클릭합니다.
  2. 원하는 경우 에이전트 이름을 변경할 수 있습니다.
  3. '간단한 인사말을 처리하고 다른 상담사에게 위임합니다'라는 설명을 입력합니다.
  4. 저장을 클릭한 다음 설정 패널을 닫습니다.

날씨 에이전트를 만듭니다.

  1. 루트 에이전트 하단에 있는 + 버튼을 클릭합니다.
  2. 새 하위 에이전트 추가를 클릭합니다.
  3. 새 에이전트의 제목 표시줄을 클릭합니다.
  4. 이름을 '날씨 에이전트'로 변경해 줘.
  5. '사용자의 날씨 관련 질문을 처리합니다'라고 설명을 입력합니다.
  6. 저장을 클릭한 다음 설정 패널을 닫습니다.

이와 유사한 방식으로 루트 에이전트의 다른 하위 에이전트를 만듭니다. 이름은 'Farewell agent'이고 설명은 'Handles user farewells and goodbyes'입니다.

에이전트 계층 구조 스크린샷

날씨 도구 만들기

도구는 에이전트를 외부 시스템 또는 에이전트에 제공된 인라인 코드에 연결하는 데 사용됩니다. 이를 통해 에이전트는 다른 시스템과 상호작용하여 정보를 가져오거나, 업데이트하거나, 형식을 지정하거나, 분석할 수 있습니다.

이 단계에서는 날씨 정보를 가져오는 데 사용되는 날씨 도구를 만듭니다. 이 가이드에서는 이 도구에 사용자를 위한 모의 응답이 있다고 가정합니다. 실제 날씨 애플리케이션에서 이 도구는 외부 서버에 액세스하여 정보를 가져옵니다.

날씨 도구를 만듭니다.

  1. 에이전트 빌더의 오른쪽에 있는 도구 버튼을 클릭합니다.
  2. +를 클릭하여 에이전트 애플리케이션의 새 도구를 만듭니다.
  3. Python 코드를 클릭합니다.

  4. 다음 코드를 붙여넣습니다.

    def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city.

  Returns:
    dict: A dictionary containing the weather information.
          Includes a 'status' key ('success' or 'error').
          If 'success', includes a 'report' key with weather details.
          If 'error', includes an 'error_message' key.
  """
  city_normalized = city.lower().replace(" ", "")

  mock_weather_db = {
    "newyork": {"status": "success",
      "report": "The weather in New York is sunny and 25°C."},
    "london": {"status": "success",
      "report": "It's cloudy in London and  15°C."},
    "tokyo": {"status": "success",
      "report": "Tokyo is experiencing light rain and 18°C."},
  }
  if city_normalized in mock_weather_db:
    return mock_weather_db[city_normalized]
  else:
    return {"status": "error",
      "error_message": f"No weather information for '{city}'."}

  5. 만들기를 클릭합니다.

이제 이 도구를 날씨 에이전트에 추가해야 합니다.

  1. 날씨 에이전트의 제목 표시줄에서 + 버튼을 클릭합니다.
  2. 도구 추가를 클릭합니다.
  3. 날씨 도구를 선택합니다.

에이전트 요청 사항 만들기

각 에이전트에는 에이전트가 해야 할 일을 정의하는 지침이 있습니다.

에이전트를 참조하는 안내를 제공할 때는 {@AGENT: Agent name} 문법을 사용하세요. 참조 도구의 경우 {@TOOL: tool_name}를 사용합니다.

각 상담사를 위한 안내를 만듭니다.

  1. 루트 에이전트의 제목 표시줄에서 + 버튼을 클릭합니다.
  2. 안내 추가를 클릭합니다.

  3. 다음 요청 사항을 입력합니다.

    You are a helpful weather application.
Your job is to greet the user and delegate to other sub-agents as needed.
When greeting the user, describe how you can help them.
When the user asks for the weather, delegate to {@AGENT: Weather agent}.
When the user is ending the conversation,
delegate to {@AGENT: Farewell agent}.
Handle only weather requests, greetings, and farewells.

  4. 만들기를 클릭합니다.

  5. 마찬가지로 날씨 에이전트에 다음 안내를 추가합니다.

    You are a helpful weather agent.
When the user asks for the weather in a specific city,
use {@TOOL: get_weather} to find the information.
If the tool returns an error, inform the user politely.
If the tool is successful, present the weather report clearly.

  6. 마찬가지로 작별 인사 에이전트에 다음 안내를 추가합니다.

    You are the Farewell Agent.
Your ONLY task is to provide a polite goodbye message.

에이전트 테스트

이제 시뮬레이터를 사용하여 에이전트 애플리케이션과 상호작용할 수 있습니다.

  1. 콘솔 화면의 왼쪽 하단에서 에이전트 미리보기 막대를 클릭하여 창을 펼칩니다(아직 펼쳐지지 않은 경우).
  2. 'hello'를 입력하고 Enter 키를 누릅니다. 에이전트가 일반적인 인사말로 응답합니다.
  3. '뉴욕 날씨는 어때?'라고 입력한 다음 Enter 키를 누릅니다. 에이전트가 날씨 정보로 응답합니다.
  4. 'goodbye'를 입력한 다음 Enter 키를 누릅니다. 상담사가 대화를 종료합니다.

변수 사용

변수는 런타임 대화 데이터를 저장하고 검색하는 데 사용됩니다. 이를 통해 에이전트는 대화 턴 전반에서 정보를 기억하여 더 맥락에 맞는 상호작용을 할 수 있습니다. 이 에이전트의 경우 사용자의 이름을 캡처하는 변수를 만듭니다.

변수를 만들려면 다음 단계를 따르세요.

  1. 에이전트 빌더의 오른쪽에 있는 변수 버튼을 클릭합니다.
  2. 변수 만들기 또는 +를 클릭합니다.
  3. 변수 이름으로 'username'을 입력합니다.
  4. 유형을 텍스트로 둡니다.
  5. 만들기를 클릭합니다.

변수를 정의했으므로 이제 에이전트가 변수를 업데이트할 수 있는 도구를 정의해야 합니다.

  1. 에이전트 빌더의 오른쪽에 있는 도구 버튼을 클릭합니다.
  2. +를 클릭하여 에이전트 애플리케이션의 새 도구를 만듭니다.
  3. Python 코드를 클릭합니다.

  4. 다음 코드를 붙여넣습니다.

    from typing import Optional

def update_username(username: str) -> Optional[str]:
  """Updates the current user's name"""
  set_variable("username", username)

  5. 만들기를 클릭합니다.

이 도구를 루트 에이전트에 추가합니다.

  1. 루트 에이전트의 제목 표시줄에서 + 버튼을 클릭합니다.
  2. 도구 추가를 클릭합니다.
  3. update_username 도구를 선택합니다.

{variable_name} 문법을 사용하여 변수를 참조하는 다음 문장을 루트 에이전트 지침에 추가합니다.

If provided, the current user is {username},
and you should address them with this name.
You can use {@TOOL: update_username} to update the user's name if they provide
it.

에이전트를 다시 테스트하여 변수 사용을 확인할 수 있습니다.

  1. 시뮬레이터 제목 표시줄에서 새 대화 시작을 클릭합니다.
  2. '안녕하세요. 제 이름은 Frank입니다'라고 입력합니다.
  3. '정보가 얼마나 정확한가요?'라고 입력합니다.

이제 에이전트가 각 응답에 내 이름을 사용하여 응답합니다. 시뮬레이터 대화의 단계 섹션을 펼쳐 도구 실행 등을 확인할 수도 있습니다.

세션 종료 방법 제어

기본적으로 각 에이전트는 end_session 시스템 도구를 사용하도록 구성되어 있지만 명시적 요청 사항을 만들어 세션을 종료하는 방법의 신뢰성과 제어력을 개선할 수 있습니다.

각 에이전트에서 도구 옆에 있는 x를 클릭하여 루트 및 날씨 에이전트에서 end_session 도구를 삭제합니다. 이렇게 하면 종료 상담사만 세션을 종료할 수 있습니다.

작별 인사 에이전트의 안내에 다음을 추가합니다.

After providing the goodbye message and confirming the user has no more
questions, execute the tool {@TOOL: end_session}(reason="success").

콜백을 사용하여 세션 종료 시 정적 메시지 강제 적용

콜백은 Python 코드를 사용하여 특정 에이전트의 실행 프로세스에 연결하는 메커니즘을 제공합니다. 이를 통해 사전 정의된 특정 시점에서 에이전트의 동작을 관찰하고, 맞춤설정하고, 제어할 수도 있습니다.

다양한 콜백 유형을 활용할 수 있으며 각 콜백 유형은 대화 턴의 특정 시점에 실행됩니다.

이 튜토리얼에서는 세션을 종료할 때 모델 응답에 정적 메시지를 추가합니다.

  1. 종료 에이전트의 제목 표시줄을 클릭합니다.
  2. 콜백 추가를 클릭합니다.
  3. After LLM(LLM 후)을 선택합니다.

  4. 다음 코드를 입력합니다.

    SURVEY_MESSAGE = "Click here to take our post call survey."

def after_model_callback(
    callback_context: CallbackContext,
    llm_response: LlmResponse
) -> Optional[LlmResponse]:
  for index, part in enumerate(llm_response.content.parts):
    if part.has_function_call('end_session'):
      return LlmResponse.from_parts(parts=[
        *llm_response.content.parts,
        Part.from_text(SURVEY_MESSAGE)

    ])
  return None

  5. 완료를 클릭합니다.

  6. 저장을 클릭합니다.

에이전트를 다시 테스트하여 세션 종료 동작을 확인할 수 있습니다.

  1. 시뮬레이터 제목 표시줄에서 새 대화 시작을 클릭합니다.
  2. 'Hello'를 입력합니다.
  3. '안녕'이라고 입력합니다.

이제 에이전트가 추가된 메시지를 사용하여 응답합니다.

구조 안내

에이전트 동작을 개선하려면 모델 처리에 최적화된 자유 형식 XML 형식으로 모든 에이전트 명령어를 구조화하면 됩니다. 각 에이전트에 대해 다음을 수행합니다.

  1. 에이전트의 안내 패널을 엽니다.
  2. 오른쪽 상단의 구조 버튼을 클릭합니다.
  3. 저장을 클릭합니다.

배포

작동하는 에이전트가 있으면 다양한 배포 옵션이 있습니다.