AI 앱에 코드 인터프리터를 추가하려면 모델이 요청한 코드 실행을 격리된 샌드박스로 라우팅하고, 범위가 지정된 파일, 명확한 패키지 정책, 리소스 및 시간 제한, 캡처된 출력, 그리고 결과가 표시되거나 저장되기 전에 애플리케이션 측 검토를 포함해야 합니다. 모델은 코드가 언제 유용한지 결정할 수 있지만, 앱은 실행 경계를 소유해야 합니다. 작업에 필요한 파일만 업로드하고, 수명이 짧은 샌드박스 세션을 생성하거나 재사용하며, 엄격한 제한 하에 Python을 실행하고, stdout, stderr, 생성된 파일 및 로그를 캡처하고, 구조화된 결과를 모델에 반환하며, 워크플로가 완료되면 세션을 정리합니다.
코드 인터프리터가 AI 앱에 추가하는 기능
코드 인터프리터는 언어 모델을 텍스트 전용 어시스턴트에서 계산, 파일 변환, 데이터 검사, 차트 생성 및 검토 가능한 아티팩트를 생성할 수 있는 도구 사용 애플리케이션으로 바꿔줍니다. 앱은 모델에게 프롬프트로 스프레드시트를 추론하도록 요청하는 대신, 모델이 Python을 작성하고, 업로드된 파일에 대해 실행하며, 출력을 검사하고, 결과를 설명하도록 할 수 있습니다.
유용한 패턴은 "모델이 무엇이든 실행하게 하는 것"이 아닙니다. 유용한 패턴은 제어된 실행 입니다. 애플리케이션이 사용자 작업을 수락하고, 모델이 run_python과 같은 도구 호출을 요청하도록 하고, 메인 애플리케이션 프로세스가 아닌 샌드박스 내에서 해당 요청을 실행합니다. 샌드박스는 임시 파일, 패키지 설치, 스크립트, 차트 및 로그를 위한 작업대가 됩니다.
코드 인터프리터 기능은 특히 다음과 같은 경우에 유용합니다:
- CSV, Excel, JSON 및 로그 분석
- 업로드된 데이터로 차트 생성
- 형식 변환 및 데이터 정리
- 정확한 계산이 필요한 수학 및 시뮬레이션 작업
- 모델이 설명하기 전에 테스트해야 하는 코드 스니펫
- 한 단계의 출력이 다음 단계의 입력이 되는 다단계 에이전트 워크플로
제한되지 않은 프로덕션 자격 증명, 개인 시스템에 대한 장기 액세스, 또는 사용자에게 보이는 감사 추적 없이 자동 실행이 필요한 작업에는 적합하지 않습니다. 결과가 금전, 인프라, 안전 또는 접근 제어에 영향을 미칠 수 있는 경우, 샌드박스 밖으로 부작용이 발생하기 전에 검토 게이트를 추가하세요.
참조 아키텍처
실용적인 코드 인터프리터 아키텍처는 다섯 부분으로 구성됩니다:
| 계층 | 책임 | 일반적인 설계 선택 |
|---|---|---|
| 사용자 인터페이스 | 파일 업로드, 진행 상황 표시, 아티팩트 표시, 승인 요청 | 업로드된 파일을 현재 대화 또는 프로젝트로 범위 지정 |
| 애플리케이션 서버 | 사용자 인증, 정책 적용, 샌드박스 세션 생성, 로그 저장 | 브라우저에 원시 샌드박스 자격 증명을 절대 노출하지 않음 |
| 모델 오케스트레이션 | 코드 도구 호출 시점 결정 및 결과 요약 | 자유 형식 텍스트를 파싱하는 대신 구조화된 도구 호출 사용 |
| 샌드박스 런타임 | Python 실행, 임시 파일 보관, 허용된 패키지 설치 | 리소스, 시간 초과 및 정리 제어로 실행 |
| 아티팩트 저장소 | 승인된 출력(차트, CSV, 보고서, 로그 등) 보존 | 앱 또는 사용자가 수락한 출력만 저장 |
모델은 인프라를 직접 제어해서는 안 됩니다. 도구 호출을 요청해야 합니다. 애플리케이션이 해당 도구 호출이 허용되는지, 어떤 파일이 첨부되는지, 얼마나 오래 실행될 수 있는지, 어떤 패키지를 사용할 수 있는지, 어떤 출력이 반환되는지 결정합니다.
이러한 분리는 모델을 유용하게 유지하면서 보안 경계로 만들지 않습니다.
구현 흐름
강력한 구현 흐름은 코드 실행 전에 시작됩니다.
1. 사용자 작업 및 파일 수락
사용자가 파일을 업로드하면 소유자, 작업 공간, 콘텐츠 유형, 크기 및 보존 정책이 포함된 애플리케이션 수준 파일 레코드로 저장합니다. 사용자 계정의 모든 파일을 인터프리터에 즉시 노출하지 마십시오. 샌드박스는 현재 작업에 필요한 파일만 수신해야 합니다.
예를 들어, 사용자가 다음과 같이 요청할 수 있습니다:
“이 CSV를 분석하고, 주요 수익 동인을 찾은 다음 차트와 짧은 설명을 반환하세요.”
앱은 업로드된 CSV를 사용 가능한 파일로 다음 모델 턴에 첨부할 수 있지만, 실제 파일 바이트는 코드 실행이 승인된 경우에만 샌드박스로 이동해야 합니다.
2. 모델이 도구 호출을 요청하도록 허용
좁은 도구 표면을 정의하세요. 일반적인 첫 번째 버전은 몇 가지 도구만 필요합니다:
{
"name": "run_python",
"arguments": {
"code": "import pandas as pd\n...",
"input_files": ["sales.csv"],
"expected_outputs": ["summary.json", "revenue_chart.png"],
"timeout_seconds": 30
}
}
스키마를 명시적으로 유지하세요. 모델은 코드, 입력 파일, 예상 출력 및 시간 초과 요청을 선언해야 합니다. 애플리케이션은 시간 초과를 단축하고, 알 수 없는 파일을 거부하거나, 정책과 충돌하는 명령을 차단할 수 있습니다.
3. 샌드박스 세션 생성 또는 재사용
일회성 어시스턴트 응답의 경우, 새 샌드박스 세션을 생성하고, 입력 파일을 업로드하고, 코드를 실행하고, 결과를 수집한 다음 세션을 종료합니다. 노트북과 같은 사용자 경험의 경우, 현재 대화 동안 세션을 활성 상태로 유지하여 이후 셀이 이전 변수와 파일을 재사용할 수 있도록 합니다.
수명이 짧은 세션은 추론하기 쉽습니다. 상태 저장 세션은 분석 작업에 더 편리합니다. 신중하게 선택하고 상태가 존재할 때 사용자에게 표시하세요.
4. Python 실행 및 결과 캡처
샌드박스 실행 API를 통해 또는 샌드박스 내에서 자체 작업자를 사용하여 코드를 실행합니다. 구조화된 실행 출력을 캡처합니다:
{
"status": "success",
"stdout": "Loaded 12,448 rows\n",
"stderr": "",
"artifacts": [
{
"path": "revenue_chart.png",
"type": "image/png",
"size_bytes": 84231
},
{
"path": "summary.json",
"type": "application/json",
"size_bytes": 1260
}
],
"duration_ms": 1840
}
이 구조화된 결과를 모델에 반환합니다. 그러면 모델은 무슨 일이 일어났는지 설명하고, 생성된 파일을 인용하며, 사용자가 다른 패스를 원하는지 물어볼 수 있습니다.
5. 사용자에게 결과 반환
실패하지 않는 한 사용자가 원시 로그를 읽도록 강요하지 마십시오. 좋은 인터페이스는 답변, 생성된 차트 또는 파일, 그리고 코드가 실행되었다는 작은 공개 정보를 표시합니다. 검토를 위해 확장 가능한 실행 로그를 제공하세요.
실패한 실행의 경우 간결한 오류를 표시하고 모델이 코드를 수정하도록 허용하세요. 사용자가 디버깅하지 않는 한 메인 채팅에 긴 역추적을 덤프하지 마십시오.
파일, 출력 및 생성된 아티팩트 처리
파일 처리는 많은 코드 인터프리터 프로젝트가 지저분해지는 부분입니다. 입력과 출력을 별개의 객체로 취급하세요.
입력 파일은 안정적이고 정리된 경로 아래에 샌드박스로 복사되어야 합니다. 공백, 셸 문자 또는 중첩된 디렉터리를 포함하는 사용자 제공 경로 이름을 유지하지 마십시오. 애플리케이션 상태에 표시 이름과 샌드박스 경로 간의 매핑을 유지하세요.
생성된 파일은 다운로드 가능한 아티팩트가 되기 전에 스캔 및 분류되어야 합니다. 차트 이미지, 정리된 CSV, JSON 요약 또는 PDF 보고서는 직접 제시해도 안전할 수 있습니다. 생성된 스크립트, 실행 파일 또는 아카이브는 더 엄격한 처리가 필요합니다.
차트 생성의 경우, 인라인 디스플레이에만 의존하지 말고 모델이 이미지 파일을 명시적으로 저장하도록 요청하세요. 데이터 분석의 경우, 자연어 설명뿐만 아니라 기계가 읽을 수 있는 요약 파일도 요청하세요. 이렇게 하면 앱이 검증하고 저장할 안정적인 무언가가 생깁니다.
유용한 아티팩트 정책은 다음과 같습니다:
| 아티팩트 유형 | 기본 처리 |
|---|---|
.png, .jpg, .webp, .svg 차트 |
크기 및 유형 검사 후 UI에서 미리보기 |
.csv, .json, .xlsx 데이터 출력 |
다운로드 제공 및 변경 사항 요약 |
.txt, .md, .pdf 보고서 |
크기에 따라 미리보기 또는 다운로드 |
.py, .sh, 바이너리, 아카이브 |
자동 실행 또는 자동 열기 금지; 명시적 검토 필요 |
앱이 영구 프로젝트를 지원하는 경우 승인된 아티팩트를 샌드박스 외부에 저장하세요. 샌드박스는 폐기 가능해야 합니다.
패키지 및 네트워크 정책 설정
대부분의 코드 인터프리터 워크플로에는 pandas, NumPy, matplotlib, seaborn, scikit-learn 또는 openpyxl과 같은 패키지가 필요합니다. 문제는 패키지가 사전 설치되어 있는지, 요청 시 설치되는지, 아니면 사용자 정의 샌드박스 템플릿에 빌드되는지 여부입니다.
사전 설치된 패키지는 실행을 예측 가능하게 유지합니다. 요청 시 설치는 유연하지만 작업 속도를 늦추고 종속성 드리프트를 유발할 수 있습니다. 사용자 정의 템플릿은 일반적인 워크로드를 알게 되면 일반적으로 최상의 프로덕션 경로입니다.
시작하기 전에 패키지 정책을 설정하세요:
- 항상 사용 가능한 패키지
- 모델이 패키지 설치를 요청할 수 있는지 여부
- 설치가 공용 패키지 인덱스에 도달할 수 있는지 여부
- 버전 고정이 필요한지 여부
- 설치가 얼마나 오래 실행될 수 있는지
- 컴파일된 패키지나 네이티브 패키지가 허용되는지 여부
네트워크 정책도 마찬가지로 중요합니다. 많은 데이터 작업은 파일이 업로드된 후 인터넷 액세스가 필요하지 않습니다. 워크플로가 외부 API가 필요한 경우, 광범위한 비밀을 샌드박스에 넣는 대신 애플리케이션 승인 도구를 통해 자격 증명을 라우팅하세요. 모델은 기본적으로 제한되지 않은 환경 변수를 받아서는 안 됩니다.
제한, 로그, 정리 및 검토 적용
코드 인터프리터는 프로덕션 기능이지 데모 셀 실행기가 아닙니다. 처음부터 제한을 두세요.
최소한의 제어 항목은 다음과 같아야 합니다:
- 셀 또는 도구 호출당 최대 실행 시간
- stdout 및 stderr의 최대 출력 크기
- 최대 아티팩트 크기 및 파일 수
- 작업에 적합한 CPU 및 메모리 제한
- 미리보기 및 다운로드를 위한 허용된 파일 확장자
- 사용자 및 작업 공간별 동시성 제한
- 임시 세션 및 파일에 대한 정리 규칙
로그는 다음 세 가지 질문에 답해야 합니다: 누가 실행을 요청했는지, 어떤 코드가 실행되었는지, 어떤 출력이 생성되었는지. 워크플로를 디버그하고 감사하기에 충분한 데이터를 저장하지만, 제품 정책이 요구하는 것보다 더 오래 개인 업로드 데이터를 보유하지 마십시오.
인간 또는 사용자 검토는 최종 제어입니다. 위험이 낮은 분석의 경우 검토는 사용자가 차트를 다운로드하기 전에 보는 것을 의미할 수 있습니다. 티켓을 업데이트하거나, 데이터베이스에 쓰거나, 외부 API를 호출할 수 있는 에이전트 워크플로의 경우 부작용이 발생하기 전에 검토가 이루어져야 하며, 이후가 아닙니다.
Novita Agent Sandbox가 적합한 위치
Novita Agent Sandbox는 코드 실행, 브라우저 워크플로, 컴퓨터 사용 스타일 작업, 평가, 강화 학습 환경 및 장기 실행 워크플로를 위한 격리된 런타임 환경이 필요한 AI 에이전트를 위해 설계되었습니다. 코드 인터프리터 기능의 경우, 이는 앱이 사용자 인증, 모델 오케스트레이션, 파일 정책, 검토 및 제품별 보존을 담당하는 동안 샌드박스가 실행 계층 역할을 할 수 있음을 의미합니다.
Novita의 샌드박스 문서에는 샌드박스에서 파일 읽기, 쓰기, 업로드, 다운로드 및 감시를 위한 파일 시스템 워크플로가 포함되어 있습니다. 이러한 기능은 코드 인터프리터 요구 사항에 직접 매핑됩니다: 사용자 파일을 실행 환경으로 이동하고, 코드가 차트 또는 변환된 데이터를 생성하도록 한 다음, 선택한 출력을 앱으로 다시 가져옵니다. 현재 파일 작업 개요는 Novita 샌드박스 파일 시스템 문서를 참조하세요.
인터프리터가 간단한 Python 실행기를 넘어 성장하는 경우, 사용자 정의 샌드박스 템플릿이 종속성 및 런타임 설정을 표준화하는 데 도움이 될 수 있습니다. 이는 모든 세션에 동일한 분석 스택, 내부 명령줄 도구 또는 프로젝트별 라이브러리가 필요할 때 유용합니다. 작은 허용 패키지 세트로 시작한 다음 워크로드가 안정화되면 반복 설정을 템플릿으로 이동하세요.
Novita 특정 통합 결정은 일반 아키텍처와 별도로 유지하세요. 코드 인터프리터에는 여전히 파일 가시성, 패키지 설치, 네트워크 액세스, 로그 보존 및 검토에 대한 애플리케이션 수준 정책이 필요합니다. 샌드박스는 제어된 런타임을 제공합니다. 제품은 해당 런타임이 사용되는 방식을 정의합니다.
평가 체크리스트
출시 전에 실제 워크플로와 적대적 프롬프트로 기능을 테스트하세요.
| 질문 | 확인할 사항 |
|---|---|
| 사용자가 올바른 파일을 업로드할 수 있습니까? | 파일 크기, 유형 검사, 소유자 검사 및 명확한 오류 메시지 |
| 모델이 깔끔하게 실행을 요청할 수 있습니까? | 코드, 입력, 예상 출력 및 시간 초과가 포함된 구조화된 도구 호출 |
| 샌드박스가 올바르게 범위 지정되었습니까? | 승인된 파일 및 환경 변수만 사용 가능 |
| 패키지가 예측 가능합니까? | 일반적인 패키지가 작동하고, 거부된 패키지는 명확하게 실패하며, 설치에 제한이 있음 |
| 출력을 사용할 수 있습니까? | 차트가 렌더링되고, 파일이 다운로드되며, 요약이 생성된 아티팩트와 일치함 |
| 오류에서 복구할 수 있습니까? | 역추적이 캡처되고, 모델이 코드를 수정할 수 있으며, 사용자에게 간결한 오류가 표시됨 |
| 제한이 적용됩니까? | 무한 루프, 대규모 출력, 메모리 집약적 작업 및 긴 설치가 종료됨 |
| 검토가 내장되어 있습니까? | 사용자가 중요한 부작용 전에 코드, 로그 및 아티팩트를 검사할 수 있음 |
| 정리가 안정적입니까? | 임시 파일 및 세션이 일정에 따라 제거되거나 만료됨 |
가장 좋은 첫 번째 릴리스는 일반적으로 좁습니다: Python 실행, 작은 패키지 세트, 파일 업로드, 차트 및 다운로드 가능한 파일, 명확한 제한 및 실행 로그. 기본 루프가 관찰 가능하고 안정적이 된 후에만 더 광범위한 패키지 설치, 영구 세션, 외부 API 액세스 및 에이전트 부작용을 추가하세요.
결론
코드 인터프리터는 모델이 실행을 요청할 수 있지만 앱이 샌드박스, 파일, 제한 및 검토 단계를 제어할 때 가장 잘 작동합니다. 좁은 Python 도구로 시작하고, 입력과 출력을 명시적으로 유지하며, 흐름이 안정된 후에만 확장하세요.
FAQ
코드 인터프리터를 추가하는 가장 안전한 방법은 무엇입니까?
격리된 샌드박스를 사용하고, 입력 파일의 범위를 지정하고, 런타임 및 메모리를 제한하고, 원시 셸 액세스 대신 구조화된 출력을 반환합니다.
모델이 패키지 설치를 제어해야 합니까?
사용자가 정의한 정책 내에서만 가능합니다. 많은 앱이 고정된 패키지 세트로 시작하고 워크로드가 필요할 때 설치를 추가합니다.
모든 코드 인터프리터 작업에 네트워크 액세스가 필요합니까?
아니요. 많은 분석 워크플로는 사용자 파일이 업로드되면 완전히 오프라인에서 작동하므로 실행 모델이 더 간단해집니다.
실행 후 사용자는 무엇을 보아야 합니까?
결과, 생성된 아티팩트, 간결한 로그 또는 오류 요약, 그리고 코드를 검사하거나 작업을 다시 실행할 수 있는 옵션.
