Agent 통합 실수 5가지

실수 1: Tool의 docstring이 모호함

# [나쁜 예]
@tool
def search(q: str) -> str:
    """검색합니다"""
    # -> Agent: "이 도구가 뭘 하는지 모르겠어..."
    # -> 도구를 사용하지 않거나 엉뚱하게 사용

# [좋은 예]
@tool
def search_documents(query: str) -> str:
    """설비 매뉴얼, 안전 규정, 작업 절차서에서 관련 내용을 검색합니다.
    설비 고장, 알람 대응, 안전 수칙에 대한 질문에 사용하세요.

    Args:
        query: 검색할 내용 (예: 'CNC 스핀들 과열 대응법')
    """
    # -> Agent: "알람 관련 질문이니 이 도구를 써야겠군!"

실수 2: Agent 무한 루프

# [문제] Agent가 같은 도구를 계속 호출
# Step 1: search_documents("E-042") -> 결과
# Step 2: search_documents("E-042 알람") -> 비슷한 결과
# Step 3: search_documents("E-042 대응") -> 또 비슷한 결과
# ... 무한 반복

# [해결 1] max_iterations 설정
agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    max_iterations=10,      # 최대 10회 반복
    max_execution_time=30,  # 최대 30초
)

# [해결 2] 시스템 프롬프트에 명시
"""
규칙:
- 같은 도구를 같은 인자로 2번 이상 호출하지 마세요
- 충분한 정보가 모이면 바로 답변하세요
- 최대 3개 도구까지만 사용하세요
"""

실수 3: 모든 질문에 도구 사용

# [나쁜 예]
사용자: "안녕하세요"
Agent: search_documents("안녕하세요")  # 불필요!
Agent: query_knowledge_graph("인사")   # 불필요!

# [해결] 시스템 프롬프트에 지침 추가
"""
도구 사용 지침:
- 일상적인 인사나 간단한 대화에는 도구를 사용하지 마세요
- 도구는 제조/설비 관련 정보가 필요할 때만 사용하세요
"""

실수 4: 에러 메시지를 사용자에게 그대로 전달

# [나쁜 예]
@tool
def query_knowledge_graph(entity_id: str) -> str:
    result = kg_service.find_related(entity_id)
    if result.error:
        return result.error  # "Neo4jError: connection refused"

# [좋은 예]
@tool
def query_knowledge_graph(entity_id: str) -> str:
    result = kg_service.find_related(entity_id)
    if result.error:
        return (
            f"'{entity_id}'의 관계 정보를 조회할 수 없습니다. "
            "Knowledge Graph 서비스가 일시적으로 사용 불가합니다."
        )

실수 5: 대화 이력 미관리

# [나쁜 예] 매 질문이 독립적
result1 = agent.run("CNC-001 상태 알려줘")
result2 = agent.run("그 설비의 부품은?")  # "그 설비"가 뭔지 모름!

# [좋은 예] 이력 전달
history = []
result1 = agent.run("CNC-001 상태 알려줘", history=history)
history = result1["messages"]  # 이력 업데이트
result2 = agent.run("그 설비의 부품은?", history=history)  # 이전 맥락 유지!