본문으로 건너뛰기

Deep Agent Builder 코드 스니펫

에이전트의 설정을 다른 호출 경로에서 재사용해야 할 때 코드 스니펫을 확인합니다. 이 페이지는 스니펫을 어디서 조회하고, 어떤 권한과 입력 형식을 확인하며, 예시에 포함된 인증값을 어떻게 다뤄야 하는지 설명합니다. 스니펫을 조회했다고 해당 호출이 실행되거나 연결된 자원이 정상이라고 판단해서는 안 됩니다.

스니펫 조회 전 확인할 것​

먼저 대상 에이전트의 공개 식별자와 현재 설정을 확인합니다. 에이전트 목록이나 수정 화면에서 보이는 이름만으로 대상을 고르지 말고, 실제로 호출하려는 에이전트인지 확인하세요.

스니펫 조회에는 에이전트 조회 권한이 필요합니다. 권한이 없거나 대상 에이전트를 볼 수 없으면 스니펫을 다시 요청하기보다 대상 범위와 권한을 확인합니다. 에이전트의 실행 권한과 스니펫 조회 권한은 같은 권한으로 취급하지 않습니다.

스니펫을 외부 호출에 사용하려면 다음 항목도 준비되어야 합니다.

  • 호출할 에이전트가 현재 사용할 모델과 지침을 갖추었는지 확인합니다.
  • 스니펫이 요구하는 입력 필드와 출력 형태를 확인합니다.
  • 호출 주체가 에이전트와 연결 자원을 사용할 권한이 있는지 확인합니다.
  • 인증 헤더나 토큰이 예시에 포함되어 있다면 실제 비밀값으로 바꾸기 전에 안전한 비밀 관리 경로를 정합니다.

스니펫 가져오기​

개인 에이전트 API에서는 다음 경로로 대상 에이전트의 스니펫을 조회합니다.

GET /user/agents/{agent_public_uid}/code-snippets

요청 형식은 formats 매개변수로 지정할 수 있으며, 이 매개변수는 반복해서 전달할 수 있습니다. 실제로 사용할 형식만 요청하고, 응답에 포함된 형식과 호출 환경이 일치하는지 확인합니다. 제품 화면에서 같은 기능을 제공하는 경우에도 화면에 표시된 대상 에이전트의 공개 식별자를 API 요청의 대상과 대조하세요.

조회 결과가 반환되면 실제로 포함된 형식과 호출 환경이 일치하는지 확인합니다. 이 기능은 스니펫을 반환하는 조회 기능이며 에이전트의 설정을 변경하거나 호출을 실행하는 기능이 아닙니다. 스니펫 조회에는 USER_AGENT_VIEW 권한이 필요하지만, 스니펫으로 실제 에이전트를 실행할 때 필요한 권한과 연결 자원 사용 권한은 별도로 확인해야 합니다.

조회 결과를 받은 뒤에는 다음 순서로 확인합니다.

  1. 대상 에이전트가 의도한 에이전트인지 공개 식별자와 이름을 대조합니다.
  2. 요청 형식과 입력 필드가 현재 연결된 모델과 자원에 맞는지 확인합니다.
  3. 인증 헤더, 토큰, 주소와 같은 실행 환경 의존 값을 실제 환경의 안전한 값으로 연결합니다.
  4. 비식별 테스트 입력으로 호출해 응답 형식과 실패 동작을 확인합니다.
  5. 정상 입력과 필수 입력이 빠진 입력을 각각 시험하고 결과를 기록합니다.

스니펫의 예시가 특정 인증 헤더를 보여 주더라도 그 문자열을 그대로 복사해 공개 저장소, 문서, 로그에 넣지 않습니다. 실제 토큰 값은 스니펫 조회 결과와 분리해 관리합니다.

호출 결과 확인​

스니펫을 복사한 뒤에는 세 가지 상태를 나눠서 판단합니다.

첫째, 스니펫 조회가 성공했는지 확인합니다. 둘째, 복사한 요청이 인증과 입력 검증을 통과했는지 확인합니다. 셋째, 에이전트가 현재 설정과 연결 자원을 사용해 기대한 결과를 반환했는지 확인합니다. 앞 단계의 성공만으로 뒤 단계의 성공을 대신할 수 없습니다.

호출이 실패하면 먼저 인증과 권한, 입력 형식, 에이전트 상태, 연결 자원의 순서로 범위를 좁힙니다. 같은 요청을 반복하기 전에 실패 응답이 가리키는 확인 지점을 기록합니다. 스니펫에 포함된 주소나 설정이 현재 환경에서 지원되는지 확인하지 않고 실행 환경의 값을 추정하지 않습니다.

설정이 바뀐 뒤 다시 조회할 때​

에이전트의 지침, 모델, 도구, 미들웨어, 스킬 또는 기타 자원을 바꿨다면 이전에 복사한 스니펫을 계속 사용하지 말고 새 스니펫과 비교합니다. 연결 자원이 바뀌면 같은 입력에서도 결과나 필요한 권한이 달라질 수 있습니다.

설정을 저장한 뒤에는 수정 화면을 다시 열어 저장 상태를 확인하고, 필요한 경우 스니펫을 다시 조회합니다. 설정 저장 성공은 호출 결과의 성공이나 답변 품질을 보장하지 않으므로, 비식별 테스트 입력으로 실제 동작을 별도로 확인합니다.

대표적인 실패와 다음 판단​

스니펫이 보이지 않으면 대상 에이전트의 공개 식별자, 조회 권한과 에이전트 소유 범위를 확인합니다. 스니펫은 보이지만 호출이 거부되면 조회 성공과 실행 권한을 분리해 확인합니다. 호출은 되지만 결과가 기대와 다르면 이름이나 설명이 아니라 지침, 모델, 연결 자원과 입력을 각각 비교합니다.

인증값이 노출된 상태로 복사됐다면 해당 값을 문서나 로그에서 지우는 것만으로 끝내지 말고 실제 비밀 관리 담당자와 교체 필요성을 확인합니다. 이 페이지는 특정 비밀 저장소나 운영 환경을 정하지 않으므로, 환경에 맞는 승인된 경로를 사용해야 합니다.

다음 문서​