에이전트 실행 환경

에이전트 실행 환경은 Triggerfish의 자체 개발 기능입니다 -- 에이전트가 코드를 작성하고, 실행하고, 출력과 오류를 관찰하고, 문제를 수정하고, 무언가가 작동할 때까지 반복할 수 있는 일급 코드 워크스페이스입니다. 이를 통해 에이전트가 자체적으로 통합을 구축하고, 아이디어를 테스트하고, 새로운 도구를 만들 수 있습니다.

Plugin 샌드박스가 아닙니다

실행 환경은 Plugin 샌드박스와 근본적으로 다릅니다. 차이를 이해하는 것이 중요합니다:

• Plugin 샌드박스는 신뢰할 수 없는 타사 코드로부터 시스템을 보호합니다
• 실행 환경은 에이전트가 자체 코드를 작성, 실행 및 디버그할 수 있도록 합니다

Plugin 샌드박스는 방어적입니다. 실행 환경은 생산적입니다. 반대 목적을 수행하며 다른 보안 프로필을 가집니다.

측면	Plugin 샌드박스	에이전트 실행 환경
목적	신뢰할 수 없는 코드로부터 시스템 보호	에이전트가 빌드하도록 권한 부여
파일 시스템	없음 (완전 샌드박스)	워크스페이스 디렉토리만
네트워크	선언된 엔드포인트만	정책 기반 허용/거부 목록
패키지 설치	허용 안됨	허용 (npm, pip, deno add)
실행 시간	엄격한 타임아웃	관대한 타임아웃 (구성 가능)
반복	단일 실행	무제한 작성/실행/수정 루프
지속성	임시	워크스페이스가 세션 간에 유지

피드백 루프

핵심 품질 차별화 요소입니다. Claude Code와 같은 도구를 효과적으로 만드는 동일한 패턴입니다 -- 에이전트가 인간 개발자가 보는 것과 정확히 동일한 것을 보는 긴밀한 작성/실행/수정 주기입니다.

1단계: 작성

에이전트가 write_file을 사용하여 워크스페이스에 파일을 생성하거나 수정합니다. 워크스페이스는 현재 에이전트에 범위가 지정된 실제 파일 시스템 디렉토리입니다.

2단계: 실행

에이전트가 run_command를 통해 코드를 실행하고 전체 stdout, stderr 및 종료 코드를 수신합니다. 출력이 숨겨지거나 요약되지 않습니다. 에이전트는 터미널에서 보는 것과 정확히 동일한 것을 봅니다.

3단계: 관찰

에이전트가 전체 출력을 읽습니다. 오류가 발생하면 전체 스택 트레이스, 오류 메시지 및 진단 출력을 봅니다. 테스트가 실패하면 어떤 테스트가 실패했고 왜 실패했는지 봅니다.

4단계: 수정

에이전트가 관찰한 내용을 기반으로 코드를 편집합니다. write_file 또는 edit_file을 사용하여 특정 파일을 업데이트합니다.

5단계: 반복

에이전트가 다시 실행합니다. 이 루프는 코드가 작동할 때까지 계속됩니다 -- 테스트 통과, 올바른 출력 생성 또는 명시된 목표 달성.

6단계: 유지

작동하면 에이전트는 작업을 스킬 (SKILL.md + 지원 파일)로 저장하거나, 통합으로 등록하거나, cron 작업에 연결하거나, 도구로 사용 가능하게 할 수 있습니다.

유지 단계는 실행 환경을 단순한 스크래치패드 이상으로 만드는 것입니다. 작동하는 코드는 사라지지 않습니다 -- 에이전트가 이를 일정에 따라 실행되거나, 트리거에 응답하거나, 필요 시 호출되는 재사용 가능한 스킬로 패키징할 수 있습니다. :::

사용 가능한 도구

도구	설명	출력
write_file	워크스페이스에 파일 작성 또는 덮어쓰기	파일 경로, 기록된 바이트
read_file	워크스페이스에서 파일 내용 읽기	문자열로 된 파일 내용
edit_file	파일에 대상 편집 적용	업데이트된 파일 내용
run_command	워크스페이스에서 셸 명령 실행	stdout, stderr, 종료 코드, 소요 시간
list_directory	워크스페이스의 파일 목록 (재귀 선택 가능)	크기가 포함된 파일 목록
search_files	파일 내용 검색 (grep과 유사)	파일:줄 참조가 포함된 일치하는 줄

워크스페이스 구조

각 에이전트는 세션 간에 유지되는 격리된 워크스페이스 디렉토리를 갖습니다:

~/.triggerfish/workspace/
  <agent-id>/                     # 에이전트별 워크스페이스
    scratch/                      # 임시 작업 파일
    integrations/                 # 개발 중인 통합 코드
      notion-sync/
        index.ts
        index_test.ts
        package.json
      salesforce-report/
        main.py
        test_main.py
    skills/                       # 저작 중인 스킬
      morning-briefing/
        SKILL.md
        briefing.ts
    .exec_history                 # 감사용 실행 로그
  background/
    <session-id>/                 # 백그라운드 작업용 임시 워크스페이스

워크스페이스는 에이전트 간에 격리됩니다. 한 에이전트가 다른 에이전트의 워크스페이스에 접근할 수 없습니다. 백그라운드 작업(cron 작업, 트리거)은 세션에 범위가 지정된 자체 임시 워크스페이스를 갖습니다.

보안 경계

실행 환경은 Plugin 샌드박스보다 더 허용적이지만 모든 단계에서 정책으로 제어됩니다.

정책 통합

• 모든 run_command 호출은 명령을 컨텍스트로 하여 PRE_TOOL_CALL 훅을 실행합니다
• 명령 허용/거부 목록이 실행 전에 확인됩니다
• 출력이 캡처되어 POST_TOOL_RESPONSE 훅을 통과합니다
• 실행 중 접근한 네트워크 엔드포인트가 계보를 통해 추적됩니다
• 코드가 분류된 데이터에 접근하면 (예: CRM API에서 읽기) 세션 테인트가 에스컬레이션됩니다
• 실행 히스토리가 감사를 위해 .exec_history에 로깅됩니다

엄격한 경계

이 경계는 구성에 관계없이 절대 넘어지지 않습니다:

• 워크스페이스 디렉토리 외부에 쓸 수 없습니다
• 거부 목록의 명령을 실행할 수 없습니다 (rm -rf /, sudo 등)
• 다른 에이전트의 워크스페이스에 접근할 수 없습니다
• 모든 네트워크 호출은 정책 훅에 의해 관리됩니다
• 모든 출력이 분류되며 세션 테인트에 기여합니다
• 리소스 제한 적용: 디스크 공간, 실행당 CPU 시간, 메모리

보안 에이전트가 실행하는 모든 명령은 PRE_TOOL_CALL 훅을 통과합니다. 정책 엔진이 실행 시작 전에 명령 허용/거부 목록에 대해 검사합니다. 위험한 명령은 결정론적으로 차단됩니다 -- LLM은 이 결정에 영향을 줄 수 없습니다. :::