구조화된 출력이 활성화된 경우 도구 호출 기능은 비활성화 되는 문제 해결 방안.

문제 요약

product_agent = LlmAgent(

    name="ProductLookupAgent",

    model=GEMINI_MODEL,

    description="Finds product details (id, name, price) given a product name or category.",

    instruction="""You are an assistant agent that helps identify products in a catalog.

                - The user will ask for a product by name or category, often with a desired quantity.

                - Use the search_product_catalog tool to find the product's details (product_id, name, price).

                - If a quantity is mentioned by the user, extract it.

                - Output **only** the product details and the quantity in a JSON format, for example:

                {"id": "...", "name": "...", "price": ..., "quantity": ...}

                - Do not add any extra explanation or text outside the JSON.

                """,

    tools=[search_product_catalog],

        output_key="product_info"

)

• 증상: 사용자 요청에 대해 search_product_catalog 함수(product_tool)가 실행되지 않고, 모델이 임의로 생성한 {"id":"…", "price":…} 형태의 JSON을 반환
• 로그 확인: 함수 내부 print("Searching catalog…") 출력이 콘솔에 전혀 나타나지 않음
• 설정: LlmAgent에 툴이 등록되어 있고, “무조건 이 툴을 사용하라”는 지시도 있음

---

2. 원인 분석

1. 출력 스키마(output_schema) 설정
   • ADK에서 output_schema를 지정하면, 에이전트는 도구 호출 없이 LLM이 스스로 JSON을 생성하도록 강제됨
   • 공식 문서에도 “구조화된 출력이 활성화된 경우 도구 호출 기능은 비활성화된다”고 명시되어 있음
2. 도구 호출 흐름 차단
   • 모델은 함수 호출 이벤트를 생성하지 않고, ‘제대로 된 JSON’을 만들기 위해 학습된 지식을 활용해 추정치를 생성
   • 따라서 실제 파이썬 함수가 실행되지 않아 로그도 찍히지 않음

---

3. 해결 방안

3.1 output_schema 제거

• LlmAgent 생성 시 output_schema 옵션을 삭제
• 대신 프롬프트(instruction)에서 “반드시 search_product_catalog 도구를 호출하라”는 지시를 명확히 유지
• 이렇게 하면 모델이 도구 호출을 통해 실제 데이터를 가져오고, 최종 답변은 JSON 형식으로 직접 출력

diff

CopyEdit

agent = LlmAgent( model="gemini-2.0-flash-001", name="product_agent", instruction=( "제품 정보를 알려면 반드시 `search_product_catalog` 도구를 호출하세요. " "도구 결과를 받아 JSON으로만 응답합니다. " "예시: {\"id\": \"P1001\", \"name\": \"Wireless Mouse\", \"price\": 25.0}" ), tools=[product_tool] - output_schema=ProductResult # 제거! )

3.2 (선택) 도구 → 포매팅 단계 분리

• 1단계: 도구 호출만 담당하는 에이전트로 실제 데이터를 조회
• 2단계: 조회 결과를 받아 output_schema 기반 포맷팅 전용 에이전트 또는 별도 함수로 JSON 엄격 검증
• 도구 호출과 출력 스키마 적용을 분리하면 양쪽 장점을 모두 활용 가능

3.3 프롬프트 강화 및 예시 추가

• “반드시 도구를 사용해야 한다”는 문구를 더 강화
• 도구 호출 예시를 짧게 few-shot형태로 포함하면 모델의 호출 확률 상승
• 가능하면 더 큰 모델(Gemini Pro 등)을 사용해 함수 호출 신뢰성 개선

---

4. 코드 실행 흐름 (정상 동작 예시)

1. 사용자 “Wireless Mouse 2개 주문하고 싶어요” 입력
2. LLM이 search_product_catalog 함수 호출 JSON 생성
3. ADK가 파이썬 함수 search_product_catalog("Wireless Mouse") 실행 → 실제 카탈로그 검색 (print 로그 확인 가능)
4. 함수가 {"id":"P1001","name":"Wireless Mouse","price":25.0} 반환
5. LLM이 이 결과를 받아 최종 JSON 응답 생성
6. 사용자에게 실제 데이터가 반영된 JSON 전달

---

5. 결론

• 핵심: output_schema 설정이 도구 호출을 막는 제약이므로, 이를 제거하고 프롬프트로 “도구 사용”을 강제하면 문제 해결
• 추가로 프롬프트 예시, 모델 선택, 로그 디버깅 등을 병행하면 더욱 안정적으로 product_tool이 호출될 수 있습니다.