ALAgent Lab Journal

← 가이드 (Guides)
...

고급 실습 랩 (ADVANCED PRACTICAL LAB)

deco Studio에서 AI 에이전트 제어하기: 도구, 권한 및 비용

      레벨: 고급 (Advanced)
      읽기 및 실습 시간: 75분
      결과물: 로컬 제어 평면 (local control plane), 테스트 에이전트, MCP 연결, 호출 로그, 그리고 토큰, 지연 시간(latency), 비용 측정값

모든 에이전트가 각자의 자격 증명(credentials)을 저장하고, 서비스에 직접 연결하며, 사용량을 서로 다르게 보고할 때, 팀은 자동화가 진정으로 유용해지기도 전에 운영 제어권을 상실하게 됩니다. 이 실습에서는 deco Studio를 제어 계층(control layer)으로 로컬에서 실행하고, 안전한 모델 컨텍스트 프로토콜 (Model Context Protocol, MCP) 서버를 연결하며, 테스트 에이전트에 단 하나의 허용된 기능만 노출하고, 실행의 전체 경로인 모델 요청, 도구 호출 (tool call), 인자 (arguments), 결과, 토큰 사용량, 지연 시간 (latency), 그리고 계산된 비용을 검사하게 됩니다. 이 가이드는 절차와 빈 측정 템플릿을 제공하며, 조작된 벤치마크 수치를 제공하지 않습니다.

운영상의 문제

세 명의 어시스턴트가 있는 팀을 가정해 봅시다. 한 명은 내부 문서를 검색하고, 다른 한 명은 프로젝트 작업을 검토하며, 세 번째 한 명은 운영 보고서를 준비합니다. 각 어시스턴트는 처음에 작은 실험으로 구축되었기 때문에, 각각 다른 클라이언트, 자격 증명 (credential), 모델 설정, 그리고 로깅 방식을 사용합니다.

이러한 구성은 다음과 같은 질문이 제기되기 전까지는 적절해 보입니다:

• 특정 답변이 생성되었을 때 어떤 도구들이 사용 가능했는가?

• 기본 서비스에 대한 액세스 권한을 누가 부여했는가?

• 에이전트가 함수에 어떤 인자 (arguments)를 보냈는가?

• 실패한 요청이 외부적인 부작용 (side effect)을 일으켰는가?

• 왜 어떤 실행은 다른 실행보다 느리거나 비용이 더 많이 들었는가?

• 입력 및 출력 토큰이 얼마나 청구되었는가?

• 팀이 모든 개발자의 컴퓨터를 일일이 방문하지 않고도 연결을 취소할 수 있는가?

• 감사자 (auditor)가 에이전트가 위험한 작업에 접근할 수 없었음을 증명할 수 있는가?

팀은 사용자, 모델, 에이전트, 그리고 외부 서비스 사이에 단일한 제어 계층 (control layer)을 구축해야 합니다. 해당 계층은 연결을 한 번만 등록하고, 의도적으로 좁게 설정된 기능 집합만을 노출하며, 서버에서 액세스 체크 (access checks)를 적용하고, 각 실행을 재구성할 수 있는 충분한 증거를 보유해야 합니다.

이 아키텍처에서 deco Studio는 로컬 제어 평면 (local control plane) 역할을 합니다. 이는 모델을 무결하게 만들거나, 안전하지 않은 업스트림 (upstream) 계정을 안전하게 만드는 것이 아닙니다. deco Studio의 역할은 에이전트 설정, 모델 경로 (model routes), MCP 연결, 권한, 그리고 실행 기록을 중앙 집중화하여 팀이 한 곳에서 액세스를 검사하고 취소할 수 있도록 하는 것입니다.

완료 기준: 테스트 에이전트가 정확히 하나의 안전한 함수를 찾아 호출할 수 있어야 하며, 제외된 함수를 성공적으로 호출할 수 없어야 하고, 연관된 실행 기록을 남겨야 합니다. 모델 단계에서는 실제 토큰 사용량과 비용을 보고하거나, 해당 측정값을 사용할 수 없는 이유를 실행 기록에 명시적으로 남겨야 합니다.

구축하게 될 내용

브라우저 또는 외부 MCP 클라이언트
                │
                ▼
...

첫 번째 도구는 운영 환경의 문서를 읽거나, 메시지를 보내거나, 리포지토리 (repository)를 변경하거나, 비즈니스 데이터베이스에 접근해서는 안 됩니다. 인위적인 입력을 사용하는 결정론적인 에코 (echo) 또는 산술 연산을 사용하세요. 제어 경로 (control path)가 검증되면, 동일한 권한 및 모니터링 원칙을 유지하면서 실제 서비스를 위한 별도의 에이전트를 생성할 수 있습니다.

이 실습이 증명하는 것

이 실습은 다음을 검증합니다:

• Studio가 로컬에서 시작되며 제어된 재시작 후에도 설정을 유지하는지;

• 하나의 모델 경로 (model route)가 정확하게 선택되고 식별되는지;

• 하나의 MCP 서버가 고정된 패키지 버전 (pinned package version)으로 연결되는지;

• 에이전트가 기본적으로 전체 연결 대신 명시적인 함수 목록 (function list)을 받는지;

• 성공적인 호출이 사용자의 요청과 상관관계가 있는지;

• 금지된 호출이 부재하거나 권한 경계 (authorization boundary)에서 거부되는지;

• 모델과 도구의 타이밍 (timing)이 혼동되지 않는지;

• 보고된 토큰 (tokens)이 비용 공식과 일치하는지;

• 알 수 없는 값 (unknown values)이 0으로 조용히 기록되는 대신 알 수 없는 상태로 유지되는지.

증명하지 않는 것

이것은 인프라 테스트이며, 복잡한 추론 (complex reasoning)에 대한 평가가 아닙니다. 짧고 결정론적인 (deterministic) 작업만으로는 모델이 실제 업무에서 잘 수행되는지 확립할 수 없습니다. 이를 위해서는 대표적인 작업, 예상 결과 및 회귀 기준 (regression criteria)을 포함하는 별도의 벤치마크 (benchmark)가 필요합니다.

또한 이 실습은 프로덕션 가용성, 백업 품질, 규제 준수, 멀티 테넌트 격리 (multi-tenant isolation) 또는 모든 악의적인 입력에 대한 저항성을 확립하지 않습니다. 그러한 요소들은 전용 테스트가 필요합니다.

시작하기 전에 "로컬"의 정의를 내리십시오

로컬 Studio 프로세스가 실행의 모든 부분이 머신에 남아 있음을 의미하지는 않습니다. 다음 세 가지 주장을 구분하십시오:

• 로컬 제어 평면 (Local control plane): Studio와 그 상태 저장소 (state store)가 사용자의 머신에서 실행됩니다.

• 로컬 추론 (Local inference): 언어 모델 (language model)이 사용자의 머신에서 실행됩니다.

• 로컬 도구 (Local tool): MCP 서버와 해당 서버가 액세스하는 모든 데이터가 머신 또는 격리된 로컬 네트워크에 머뭅니다.

이 실습은 오직 첫 번째 조건만을 보장합니다. 외부 모델 제공자 (external model provider)를 구성하면, 프롬프트 (prompts)와 도구 스키마 (tool schemas)는 해당 제공자의 경로에 따라 머신을 떠납니다. 원격 MCP 엔드포인트 (remote MCP endpoint)에 연결하면, 도구 인자 (tool arguments)와 결과가 해당 서비스로 전송됩니다.

실행 여권 (run passport)에 세 가지 경계(boundaries)를 모두 기록하십시오. 기술적으로 로컬인 사용자 인터페이스 (user interface)라 할지라도, 각 네트워크 홉 (network hop)을 검증하지 않았다면 완전히 로컬인 실행 경로 (execution path)로 제시해서는 안 됩니다.

1. 실행 여권 (run passport) 생성

어떠한 프로덕션 리포지토리 (production repository) 외부에도 작업 디렉토리를 생성하십시오. 여기에는 설정 노트 (configuration notes)와 비식별 처리된 증거 (redacted evidence)가 포함되지만, 자격 증명 (credentials)은 포함되지 않습니다:

mkdir -p deco-control-lab/screenshots
cd deco-control-lab
touch README.md run-log.csv permission-matrix.csv
...

Studio를 변경하기 전에, README.md에 다음 필드들을 배치하십시오:

Test date:
Time zone:
Operating system:
...

가격 출처 (price source) 필드는 본인의 증거를 위한 노트입니다. 모델 식별자 (model identifiers)와 요금 (tariffs)은 변경되므로, 이 기사에서는 현재 가격을 제공하지 않습니다. 실제 실행 시 사용한 제공업체로부터 적용 가능한 요율을 확보하고 날짜를 기록하십시오.

권한 매트릭스 (Permission matrix)

permission-matrix.csv에 다음 헤더를 사용하십시오:

subject,connection,tool,expected,reason,verified_at,evidence

매트릭스는 테스트 전의 의도된 액세스 (access)를 설명합니다. verified_at 및 evidence 필드는 관찰 후에만 채워집니다.

실행 로그 (Run log)

모든 실행에 대해 별도의 행을 사용하십시오:

run_id,started_at,agent,model,prompt_case,status,
input_tokens,output_tokens,total_tokens,
first_model_latency_ms,tool_latency_ms,final_model_latency_ms,total_latency_ms,
...

명시적인 시간대 (time zone)를 포함한 ISO 8601 타임스탬프 (timestamps)를 사용하십시오. 만약 Studio가 실행 (run) 또는 트레이스 (trace) 식별자를 노출한다면 이를 보존하십시오. 그렇지 않다면 LAB-001과 같은 식별자를 생성하고, 나중에 찾을 수 있도록 사용자 요청 (user request)에 포함시키십시오.

여권 (passport)에 비밀 정보 (secrets)를 저장하지 마십시오. API 키 (API keys), 인증 헤더 (authorization headers), 비식별 처리되지 않은 도구 결과 (unredacted tool results), 환경 덤프 (environment dumps), 데이터베이스 내보내기 (database exports)는 CSV 파일이나 스크린샷에 포함되어서는 안 됩니다. 자격 증명 (credentials)은 지원되는 비밀 저장소 (secret store)에 저장하고, 실행 기록에는 민감하지 않은 자격 증명 라벨 (credential label)만 유지하십시오.

2. 로컬 환경 점검

필요한 명령어가 존재하는지 확인하고, Studio가 의도한 포트(port)가 이미 사용 중인지 확인하십시오:

bun --version
node --version
npm --version
...

macOS에서는 다음을 사용하십시오:

lsof -nP -iTCP:3000 -sTCP:LISTEN

포트가 사용 중이라면, 조치를 취하기 전에 해당 프로세스를 식별하십시오. 단순히 포트를 비우기 위해 알 수 없는 서비스를 종료하지 마십시오. 이미 알고 있는 개발 프로세스를 중단하거나, 설치한 Studio 버전에서 지원하는 포트 설정을 사용하십시오.

Studio 버전 고정하기

게시된 패키지 버전을 검사하고 기록하십시오:

npm view decocms version

확인된 버전을 아래에 대입하십시오:

export DECO_LAB_VERSION="<확인된-버전>"
bunx -p "decocms@${DECO_LAB_VERSION}" deco

재현 가능한 실행(repeatable run)을 위해 latest를 사용하지 마십시오. 유동적인 릴리스(floating release)는 두 테스트 사이에 데이터베이스 동작, 연결 필드, 에이전트(agent) 설정 또는 인터페이스 라벨을 변경할 수 있습니다.

설치된 릴리스가 다른 지원되는 실행 명령어를 사용하는 경우, 해당 특정 릴리스와 함께 제공된 명령어를 사용하고 이를 패스포트(passport)에 기록하십시오. 중요한 속성은 명령어의 철자가 아니라 동일한 환경을 재현할 수 있는 능력입니다.

프로세스 검증

• 명령어가 치명적인 오류(fatal error) 없이 계속 실행 중인지;
• Studio가 로컬 주소(local address)를 보고하거나 노출하는지;
• 브라우저에서 페이지가 응답하는지;
• 패키지 버전이 기록되었는지;
• 데이터 위치를 알 수 있거나 찾을 수 있는지;
• 포트가 신뢰할 수 없는 네트워크에 노출되지 않았는지.

필요한 경우 포트를 교체한 후 수행할 수 있는 유용한 HTTP 체크 방법은 다음과 같습니다:

curl -I http://127.0.0.1:3000/

정확한 상태와 리다이렉트(redirect) 동작은 릴리스에 따라 다릅니다. 유효한 HTTP 응답은 프로세스가 리스닝(listening) 중이라는 증거로 취급해야 하며, 애플리케이션이 완전히 구성되었다는 증거로 취급해서는 안 됩니다.

3. 격리된 조직 생성

첫 로그인 후, agent-control-lab 또는 다른 명확하게 임시적인 이름을 가진 조직(organization)을 생성하세요. 이미 운영용 연결(production connections)이 포함된 조직에서는 실험을 수행하지 마십시오.

다음 항목에 해당하는 영역을 찾으십시오:

• 연결(connections) 또는 MCP 서버;
• 에이전트(agents) 및 해당 도구(tools);
• 모델(model) 또는 AI 제공업체(AI providers);
• 멤버(members) 및 역할(roles);
• API 키(API keys) 또는 외부 클라이언트 자격 증명(external-client credentials);
• 모니터링(monitoring), 로그(logs), 실행(runs) 또는 트레이스(traces).

레이블(Labels)은 릴리스에 따라 변경될 수 있습니다. 이 가이드와 설치된 인터페이스 간의 불일치가 있다면 기록하십시오. 설정이 자격 증명(credentials)이나 권한(permissions)에 영향을 미치는 경우, 추측하여 클릭하지 마십시오.

역할 경계 계획하기

            역할 (Role)
            허용된 책임 (Permitted responsibilities)
            분리하여 유지해야 할 책임 (Responsibilities to keep separate)
...

효과적인 액세스(access)는 사용자 역할(user role), 클라이언트 자격 증명(client credential), 에이전트 구성(agent configuration), 연결 정책(connection policy) 및 상위 계정(upstream account)의 교집합입니다. 에이전트를 실행할 권한이 있다고 해서 에이전트에 새로운 도구를 연결할 권한까지 포함하는 것은 아닙니다.

4. 하나의 모델 경로 구성하기

전용 테스트 자격 증명을 가진 외부 제공업체(external provider)를 사용하거나, 설치된 Studio 버전에서 지원하는 로컬 모델 엔드포인트(local model endpoint)를 사용하십시오. 첫 번째 실험은 정확히 하나의 모델로 제한하고, 폴백 경로(fallback routes)는 비활성화하거나 문서화하십시오.

외부 제공업체

해당 옵션이 있는 경우, 제공업체 측 예산(budget)이 설정된 제한된 테스트 자격 증명을 생성하십시오. 이는 Studio의 제공업체(provider) 또는 비밀 설정(secret configuration)을 통해서만 입력하십시오. 에이전트 지침(agent instruction), 채팅 메시지, 스크린샷 또는 소스 제어(source control)에 커밋되는 MCP 클라이언트 파일에 절대 포함하지 마십시오.

다음 사항을 기록하십시오:

• 정확한 제공업체(provider);
• 실행 시 반환된 정확한 모델 식별자(model identifier);
• 100만 토큰당 입력 가격(input price per million tokens);
• 100만 토큰당 출력 가격(output price per million tokens);
• 통화(currency);
• 가격을 확인한 날짜;
• 캐시된 입력(cached input), 추론(reasoning) 또는 기타 토큰 클래스에 대한 별도의 요율;
• 제공업체가 도구 호출(tool-calling) 요청에 대한 사용량을 보고하는지 여부.

로컬 모델

프라이빗한 실행 경로(execution route)를 조사하는 것이 목표라면, OpenAI 호환(OpenAI-compatible) 로컬 엔드포인트가 적절할 수 있습니다. 이러한 모델의 경우 토큰당 제공업체 요율(provider tariff)이 없기 때문에 Studio에는 비용이 0이거나 비용 없음으로 표시될 수 있습니다.

이를 총비용이 0이라는 의미로 해석해서는 안 됩니다. 하드웨어, 전기, 저장 장치 및 운영자 시간은 여전히 존재합니다. 수용 가능한 할당 방법이 없는 경우, 제공업체 토큰 과금(provider token billing)에는 not_applicable을 기록하고 로컬 인프라 비용은 별도로 기술하십시오.

실험을 위한 라우팅 고정 (Freeze routing for the lab)

Model tier: <selected-tier>
Configured model: <exact-model-id>
Provider: <provider-name>
...

Zero(0), unknown(알 수 없음), 그리고 not_applicable(해당 없음)은 서로 다른 값입니다. 관련 과금 요소가 무료임이 확인된 경우에만 0을 사용하십시오. 사용량은 존재하지만 노출되지 않는 경우에는 not_reported를 사용하고, 가격 모델이 해당 요소를 사용하지 않는 경우에는 not_applicable을 사용하십시오.

5. 안전한 MCP 서버 연결하기

합성 작업(synthetic operations)만 포함된 데모 서버로 시작하십시오. 만약 사용 중인 Studio 릴리스가 로컬 STDIO 연결을 지원한다면, MCP SDK 생태계의 테스트 서버를 통해 결정론적 함수(deterministic functions)를 제공받을 수 있습니다:

npm view @modelcontextprotocol/server-everything version

제한 없는 패키지를 실행하는 대신 관찰된 버전을 고정(Pin)하십시오:

npx -y @modelcontextprotocol/server-everything@<observed-version>

Studio에서 lab-mcp-safe라는 이름의 커스텀 연결을 생성합니다. 설치된 릴리스가 선택한 배포 모드에서 해당 전송 방식(transport)을 지원하는 경우에만 STDIO를 선택하십시오. 다음과 같이 구성합니다:

Command: npx
Arguments:
  - -y
...