출력

​

개요

• 응답 형식 정의 - 에이전트 응답을 위한 사용자 지정 JSON 스키마 생성
• 일관성 보장 - 에이전트가 항상 동일한 구조로 데이터를 반환하도록 보장
• 통합 가능 - 다른 시스템에서 응답을 쉽게 소비할 수 있게 함
• 파싱 개선 - 복잡한 텍스트 파싱 필요성 제거

​

작동 방식

​

1. JSON 스키마 생성

• 필드 - 필수 및 선택 필드 지정
• 데이터 유형 - 유형 정의 (문자열, 숫자, 부울, 배열, 객체)
• 중첩 구조 - 복잡한 중첩 JSON 객체 생성
• 예시 - 명확성을 위한 예시 값 제공

​

2. 에이전트에 할당

• 일반 탭 - 사용 가능한 구조화된 출력 중에서 선택
• 에이전트별 - 각 에이전트는 다른 스키마를 사용할 수 있음
• 동적 선택 - 필요에 따라 스키마 변경

​

3. 에이전트 응답

• JSON으로 형식화 - 지정된 JSON 구조로 응답 반환
• 스키마 준수 - 모든 필수 필드 포함
• 구조 유지 - 중첩 객체 및 배열 보존
• 형식 검증 - 응답이 스키마와 일치하는지 확인

​

구조화된 출력 생성

​

1단계: 출력 탭에 접근

1. 사이드바에서 에이전트로 이동
2. 에이전트를 선택하거나 새로 만들기
3. 편집을 클릭하여 에이전트 빌더 열기
4. 출력 탭으로 이동

​

2단계: 새 스키마 생성

1. 새로 만들기 버튼 클릭
2. 구조화된 출력에 대한 설명적인 제목 입력
3. JSON 빌더를 사용하여 스키마 정의

​

3단계: 스키마 구조 정의

​

기본 구조

{
  "status": "string",
  "message": "string",
  "data": {
    "result": "string"
  }
}

​

배열 포함

{
  "items": [
    {
      "id": "string",
      "name": "string",
      "value": "number"
    }
  ],
  "total": "number"
}

​

복잡한 중첩 구조

{
  "response": {
    "summary": "string",
    "details": {
      "category": "string",
      "subcategory": "string",
      "metadata": {
        "created_at": "string",
        "updated_at": "string"
      }
    },
    "items": [
      {
        "id": "string",
        "properties": {
          "name": "string",
          "value": "number"
        }
      }
    ]
  }
}

​

4단계: 스키마 저장

1. 저장을 클릭하여 구조화된 출력을 저장
2. 스키마가 이제 에이전트에서 사용할 수 있게 됨

​

에이전트에 할당

​

방법 1: 일반 탭에서

1. 구성할 에이전트를 엽니다
2. 일반 탭으로 이동
3. 응답 형식 섹션을 찾습니다
4. 드롭다운에서 구조화된 출력을 선택
5. 에이전트를 저장합니다

​

방법 2: 출력 탭에서

1. 구성할 에이전트를 엽니다
2. 출력 탭으로 이동
3. 목록에서 구조화된 출력을 선택
4. 에이전트는 모든 응답에 이 스키마를 사용합니다

​

사용 사례

​

API 통합

{
  "status": "success",
  "code": 200,
  "data": {
    "result": "string",
    "timestamp": "string"
  }
}

{
  "status": "success",
  "code": 200,
  "data": {
    "result": "태스크가 성공적으로 완료되었습니다",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

​

데이터 추출

{
  "entities": [
    {
      "type": "string",
      "value": "string",
      "confidence": "number"
    }
  ],
  "summary": "string"
}

​

형식화된 보고서

{
  "report": {
    "title": "string",
    "date": "string",
    "sections": [
      {
        "heading": "string",
        "content": "string",
        "metrics": {
          "value": "number",
          "unit": "string"
        }
      }
    ],
    "summary": "string"
  }
}

​

워크플로우 자동화

{
  "action": "string",
  "parameters": {
    "key": "value"
  },
  "next_step": "string",
  "metadata": {
    "workflow_id": "string",
    "step_number": "number"
  }
}

​

모범 사례

​

스키마 설계

1. 구체적으로 작성 - 모든 필드와 유형을 명확하게 정의
2. 예시 사용 - 스키마에 예시 값 포함
3. 단순하게 유지 - 가능한 경우 과도하게 복잡한 중첩 구조를 피함
4. 필드 문서화 - 설명적인 필드 이름 사용
5. 선택 필드 고려 - 적절할 때 필드를 선택 사항으로 표시

​

필드 명명

• 명확한 이름 사용 - un 대신 user_name
• 일관성 유지 - 명명 규칙 따르기 (snake_case, camelCase)
• 약어 사용 금지 - 가능한 경우 전체 단어 사용
• 관련 필드 그룹화 - 관련 데이터에 중첩 객체 사용

​

스키마 구조

• 가능하면 평탄하게 - 단순한 데이터의 경우 평탄한 구조 선호
• 조직화를 위해 중첩 - 복잡하고 관련된 데이터에 중첩 사용
• 리스트에 배열 - 유사 항목의 컬렉션에 배열 사용
• 그룹에 객체 - 관련 필드를 그룹화하기 위해 객체 사용

​

테스트

1. 실제 쿼리로 테스트 - 실제 사용자 질문으로 스키마가 작동하는지 확인
2. 모든 필드 확인 - 모든 필수 필드가 채워져 있는지 확인
3. 유형 검증 - 데이터 유형이 스키마와 일치하는지 확인
4. 엣지 케이스 처리 - 비정상적이거나 누락된 데이터로 테스트

​

구조화된 출력 관리

​

모든 스키마 보기

• 모든 스키마 나열 - 프로젝트의 모든 구조화된 출력 표시
• 검색 - 이름으로 스키마 찾기
• 정렬 - 생성 날짜 또는 제목으로 정렬
• 세부 정보 보기 - 스키마 구조 및 메타데이터 확인

​

스키마 편집

1. 목록에서 스키마를 클릭
2. 시각적 빌더를 사용하여 JSON 구조 수정
3. 저장을 클릭하여 스키마 업데이트
4. 변경 사항은 이 스키마를 사용하는 모든 에이전트에 적용

​

스키마 삭제

1. 목록에서 스키마를 찾습니다
2. 삭제 아이콘을 클릭
3. 삭제를 확인
4. 이 스키마를 사용하는 에이전트는 일반 텍스트 응답으로 복귀

​

트러블슈팅

​

에이전트가 스키마를 따르지 않음

• 스키마가 에이전트에 할당되지 않음
• 스키마 구조가 너무 복잡함
• 에이전트에 더 명확한 지침이 필요함

• 일반 탭에서 구조화된 출력이 선택되었는지 확인
• 스키마 구조를 단순화
• 더 명시적인 필드 설명 추가
• 더 간단한 쿼리로 먼저 테스트

​

잘못된 JSON 응답

• 스키마에 구문 오류가 있음
• 에이전트가 복잡한 구조로 어려움 겪음
• 필수 필드 누락

• JSON 빌더에서 스키마 구문 검증
• JSON 검증 오류 확인
• 스키마가 너무 복잡한 경우 단순화
• 응답에서 파싱 오류 검토

​

관련 기능

• 에이전트 구성 - 에이전트 성격 및 동작 구성
• 도구 - 구조화된 데이터를 반환하는 도구 사용
• API 통합 - 구조화된 응답을 외부 API와 통합
• 워크플로우 - 자동화된 워크플로우에서 구조화된 출력 사용

​

지원