Agent 시스템 핵심 분석 완벽 가이드

AI Agent 시스템의 핵심 구조를 파헤칩니다. 네임스페이스부터 권한 시스템, 커스텀 에이전트 정의까지 초급 개발자도 이해할 수 있도록 실무 예제와 함께 설명합니다.

---

목차

1. Agent_네임스페이스_구조
2. 빌트인_에이전트
3. 에이전트_설정과_권한_시스템
4. Permission_시스템
5. 에이전트별_도구_제한
6. 커스텀_에이전트_정의하기

---

1. Agent 네임스페이스 구조

김개발 씨는 회사에서 AI Agent 시스템을 처음 접하게 되었습니다. 수많은 파일과 폴더를 보며 어디서부터 시작해야 할지 막막했습니다.

선배 박시니어 씨가 다가와 말했습니다. "먼저 네임스페이스 구조부터 이해해야 해요.

이게 전체 시스템의 뼈대거든요."

네임스페이스는 관련된 코드를 하나의 논리적 단위로 묶어주는 구조입니다. 마치 도서관에서 책을 주제별로 분류하는 것과 같습니다.

Agent 시스템에서는 이 네임스페이스를 통해 각 에이전트의 역할과 기능을 명확하게 구분합니다.

다음 코드를 살펴봅시다.

// Agent 네임스페이스 기본 구조
namespace Agent {
  // 에이전트 타입 정의
  export type AgentType = 'build' | 'plan' | 'explore' | 'general';

  // 에이전트 설정 인터페이스
  export interface AgentConfig {
    name: string;
    type: AgentType;
    permissions: Permission[];
    tools: Tool[];
  }

  // 에이전트 인스턴스 생성 함수
  export function createAgent(config: AgentConfig): AgentInstance {
    return new AgentInstance(config);
  }
}

김개발 씨는 입사한 지 얼마 되지 않은 주니어 개발자입니다. 오늘 처음으로 AI Agent 프로젝트에 투입되었는데, 프로젝트 폴더를 열어보니 수십 개의 파일이 복잡하게 얽혀 있었습니다.

도대체 어디서부터 시작해야 할까요? 선배 박시니어 씨가 커피 한 잔을 건네며 다가왔습니다.

"처음엔 다들 그래요. 하지만 걱정 마세요.

핵심은 네임스페이스 구조를 이해하는 거예요." 그렇다면 네임스페이스란 정확히 무엇일까요? 쉽게 비유하자면, 네임스페이스는 마치 대형 백화점의 층별 안내도와 같습니다.

1층은 화장품, 2층은 여성복, 3층은 남성복처럼 각 층마다 관련된 상품들이 모여 있습니다. 고객은 원하는 물건이 어디에 있는지 쉽게 찾을 수 있고, 매장 직원들도 자기 담당 구역만 관리하면 됩니다.

네임스페이스도 이와 똑같은 역할을 합니다. 네임스페이스가 없던 시절에는 어땠을까요?

모든 함수와 변수가 하나의 전역 공간에 뒤섞여 있었습니다. 이름이 충돌하는 문제가 빈번했고, 코드가 커질수록 어떤 기능이 어디에 있는지 찾기가 점점 어려워졌습니다.

협업할 때는 더 큰 문제가 생겼습니다. 동료가 만든 함수 이름과 내가 만든 함수 이름이 같으면 예상치 못한 버그가 발생했습니다.

바로 이런 문제를 해결하기 위해 네임스페이스가 등장했습니다. Agent 시스템에서 네임스페이스는 AgentType, AgentConfig, Permission 등의 관련 요소들을 하나로 묶어줍니다.

덕분에 코드를 읽는 사람은 Agent라는 네임스페이스만 보면 에이전트와 관련된 모든 것이 여기에 있다는 것을 즉시 알 수 있습니다. 위의 코드를 살펴보겠습니다.

먼저 namespace Agent로 시작하는 부분이 보입니다. 이것이 바로 Agent라는 이름의 네임스페이스를 선언하는 것입니다.

그 안에 AgentType이라는 타입이 정의되어 있는데, 이는 에이전트가 가질 수 있는 종류를 명시합니다. build, plan, explore, general 네 가지가 있네요.

다음으로 AgentConfig 인터페이스가 있습니다. 에이전트를 생성할 때 필요한 설정 정보의 구조를 정의합니다.

이름, 타입, 권한, 도구 목록이 필요하다는 것을 한눈에 알 수 있습니다. 마지막으로 createAgent 함수는 설정을 받아서 실제 에이전트 인스턴스를 만들어냅니다.

export 키워드가 붙어 있어서 네임스페이스 외부에서도 사용할 수 있습니다. 실제 현업에서는 이 구조가 어떻게 활용될까요?

대규모 AI 서비스를 개발한다고 가정해봅시다. 코드 생성을 담당하는 팀, 문서 분석을 담당하는 팀, 대화 처리를 담당하는 팀이 각각 있습니다.

네임스페이스를 활용하면 각 팀이 자신의 영역에서 독립적으로 개발하면서도 전체 시스템과 자연스럽게 통합될 수 있습니다. 박시니어 씨의 설명을 들은 김개발 씨는 고개를 끄덕였습니다.

"아, 그래서 코드가 이렇게 구조화되어 있었군요!" 네임스페이스를 이해하니 복잡해 보이던 프로젝트가 한결 명확하게 다가왔습니다.

실전 팁

💡 - 네임스페이스 내부에서 외부로 공개할 요소에만 export를 붙이세요

• 네임스페이스 이름은 해당 도메인을 명확히 나타내는 이름으로 짓는 것이 좋습니다

---

2. 빌트인 에이전트

김개발 씨가 에이전트 시스템의 구조를 이해하고 나니, 이번에는 실제로 어떤 에이전트들이 있는지 궁금해졌습니다. 박시니어 씨가 화이트보드에 네 개의 원을 그리며 말했습니다.

"기본으로 제공되는 빌트인 에이전트가 네 가지 있어요. 각각 역할이 완전히 다르답니다."

빌트인 에이전트는 시스템에서 기본으로 제공하는 핵심 에이전트들입니다. build는 코드 생성, plan은 작업 계획 수립, explore는 코드베이스 탐색, general은 범용 대화를 담당합니다.

마치 회사의 핵심 부서처럼 각자의 전문 영역이 있습니다.

다음 코드를 살펴봅시다.

// 빌트인 에이전트 정의
const builtinAgents = {
  // 코드 생성 전문 에이전트
  build: {
    name: 'Build Agent',
    purpose: 'Generate and modify code',
    tools: ['write', 'edit', 'bash'],
    model: 'claude-sonnet'
  },
  // 작업 계획 수립 에이전트
  plan: {
    name: 'Plan Agent',
    purpose: 'Create implementation strategies',
    tools: ['read', 'glob', 'grep'],
    model: 'claude-opus'
  },
  // 코드베이스 탐색 에이전트
  explore: {
    name: 'Explore Agent',
    purpose: 'Navigate and understand codebase',
    tools: ['read', 'glob', 'grep', 'webSearch'],
    model: 'claude-haiku'
  },
  // 범용 대화 에이전트
  general: {
    name: 'General Agent',
    purpose: 'Handle general conversations',
    tools: ['*'],  // 모든 도구 사용 가능
    model: 'claude-sonnet'
  }
};

김개발 씨는 네임스페이스 구조를 배우고 나서 자신감이 붙었습니다. 이제 실제로 동작하는 에이전트들에 대해 알고 싶어졌습니다.

어떤 에이전트들이 있고, 각각 무슨 일을 하는 걸까요? 박시니어 씨가 화이트보드 앞으로 가더니 네 개의 원을 그렸습니다.

"Agent 시스템에는 기본으로 제공되는 빌트인 에이전트가 네 가지 있어요." 쉽게 비유하자면, 빌트인 에이전트는 마치 병원의 전문의들과 같습니다. 내과, 외과, 정형외과, 가정의학과처럼 각 전문 분야가 있고, 환자의 증상에 따라 적절한 전문의에게 연결됩니다.

에이전트도 마찬가지로 각자의 전문 영역이 있어서 요청의 성격에 따라 적합한 에이전트가 처리합니다. 첫 번째는 build 에이전트입니다.

build 에이전트는 코드 생성과 수정을 담당하는 전문가입니다. 새로운 기능을 구현하거나 버그를 수정할 때 이 에이전트가 나섭니다.

write, edit, bash 같은 도구를 사용할 수 있어서 실제로 파일을 만들고 수정하는 것이 가능합니다. 두 번째는 plan 에이전트입니다.

plan 에이전트는 전략가입니다. 복잡한 작업을 어떻게 수행할지 계획을 세웁니다.

코드를 직접 수정하지는 않지만, 전체 구조를 파악하고 최적의 구현 방안을 제시합니다. 마치 건축가가 집을 짓기 전에 설계도를 그리는 것과 같습니다.

세 번째는 explore 에이전트입니다. explore 에이전트는 탐험가입니다.

코드베이스를 빠르게 탐색하고 필요한 정보를 찾아냅니다. 특히 처음 접하는 프로젝트에서 구조를 파악할 때 큰 도움이 됩니다.

가벼운 모델을 사용해서 빠른 응답이 가능합니다. 네 번째는 general 에이전트입니다.

general 에이전트는 만능 해결사입니다. 다른 세 에이전트의 영역에 딱 들어맞지 않는 요청을 처리합니다.

모든 도구에 접근할 수 있어서 유연하게 대응할 수 있습니다. 코드에서 주목할 점이 있습니다.

각 에이전트마다 사용할 수 있는 tools가 다릅니다. build 에이전트는 코드를 수정해야 하니까 write와 edit 도구가 있고, explore 에이전트는 읽기 전용 도구만 가지고 있습니다.

general 에이전트의 tools가 ['*']인 것은 모든 도구를 사용할 수 있다는 의미입니다. 또한 model 설정도 다릅니다.

plan처럼 깊은 사고가 필요한 에이전트는 더 강력한 모델을, explore처럼 빠른 응답이 중요한 에이전트는 가벼운 모델을 사용합니다. 김개발 씨가 질문했습니다.

"그러면 제가 무언가를 요청하면 시스템이 알아서 적절한 에이전트를 선택하는 건가요?" 박시니어 씨가 고개를 끄덕였습니다. "맞아요.

하지만 때로는 직접 지정할 수도 있어요."

실전 팁

💡 - 코드 생성이 필요할 때는 build, 구조 파악이 필요할 때는 explore를 명시적으로 지정하면 더 좋은 결과를 얻을 수 있습니다

• 각 에이전트의 model 설정은 비용과 성능의 균형을 고려해서 결정하세요

---

3. 에이전트 설정과 권한 시스템

김개발 씨는 빌트인 에이전트의 종류를 알게 되었습니다. 그런데 문득 궁금해졌습니다.

"에이전트가 아무 파일이나 수정할 수 있으면 위험하지 않나요?" 박시니어 씨가 미소 지으며 말했습니다. "좋은 질문이에요.

바로 그래서 설정과 권한 시스템이 있는 거예요."

에이전트 설정은 에이전트의 행동 범위와 능력을 정의합니다. 권한 시스템은 에이전트가 무엇을 할 수 있고 없는지를 제어합니다.

마치 회사에서 직급에 따라 접근 가능한 정보가 다른 것처럼, 에이전트도 설정된 권한 내에서만 작동합니다.

다음 코드를 살펴봅시다.

// 에이전트 설정 구조
interface AgentSettings {
  // 기본 설정
  name: string;
  description: string;
  model: 'haiku' | 'sonnet' | 'opus';

  // 권한 설정
  permissions: {
    fileSystem: FilePermission;
    network: NetworkPermission;
    execution: ExecutionPermission;
  };

  // 컨텍스트 설정
  contextWindow: number;
  maxTokens: number;
}

// 설정을 적용한 에이전트 생성
function configureAgent(settings: AgentSettings): Agent {
  validatePermissions(settings.permissions);
  return new Agent(settings);
}

김개발 씨는 빌트인 에이전트들의 역할을 이해했습니다. 하지만 한 가지 걱정이 생겼습니다.

에이전트가 코드를 수정할 수 있다면, 실수로 중요한 파일을 망가뜨리면 어떡하죠? 프로덕션 데이터베이스 설정 파일을 건드리기라도 하면 큰일이 날 것 같았습니다.

박시니어 씨가 안심시켜 주었습니다. "걱정 마세요.

바로 그런 상황을 방지하기 위해 설정과 권한 시스템이 있어요." 쉽게 비유하자면, 이것은 마치 호텔의 카드키 시스템과 같습니다. 손님은 자기 방에만 들어갈 수 있고, 청소 직원은 모든 객실에 들어갈 수 있지만 금고는 열 수 없습니다.

매니저만이 모든 공간에 접근할 수 있죠. 에이전트 시스템도 이와 같은 원리로 작동합니다.

에이전트 설정은 크게 세 부분으로 나뉩니다. 첫 번째는 기본 설정입니다.

에이전트의 이름, 설명, 그리고 사용할 AI 모델을 지정합니다. 모델에 따라 에이전트의 능력과 응답 속도가 달라집니다.

두 번째는 권한 설정입니다. 이 부분이 보안의 핵심입니다.

파일 시스템 접근 권한, 네트워크 사용 권한, 코드 실행 권한을 각각 설정할 수 있습니다. 예를 들어 어떤 에이전트는 특정 폴더만 읽을 수 있고, 다른 에이전트는 외부 API를 호출할 수 없도록 제한할 수 있습니다.

세 번째는 컨텍스트 설정입니다. 에이전트가 한 번에 처리할 수 있는 정보의 양을 정의합니다.

contextWindow는 대화 맥락의 크기, maxTokens는 응답의 최대 길이를 의미합니다. 코드에서 validatePermissions 함수를 주목해 보세요.

에이전트를 생성하기 전에 권한 설정이 올바른지 검증합니다. 잘못된 권한 조합이나 위험한 설정은 여기서 걸러집니다.

실제 현업에서는 이 시스템이 매우 중요합니다. 예를 들어 고객 데이터를 다루는 서비스에서 에이전트가 개인정보가 담긴 파일에 접근하면 안 됩니다.

권한 시스템을 통해 민감한 경로를 차단할 수 있습니다. 또한 테스트 환경의 에이전트와 프로덕션 환경의 에이전트는 서로 다른 권한을 가져야 합니다.

주의할 점도 있습니다. 권한을 너무 느슨하게 설정하면 보안 위험이 생기고, 너무 엄격하게 설정하면 에이전트가 제 역할을 못 합니다.

적절한 균형을 찾는 것이 중요합니다. 김개발 씨가 이해했다는 듯 말했습니다.

"아, 그래서 아까 코드에서 build 에이전트와 explore 에이전트의 도구 목록이 달랐군요!" 박시니어 씨가 엄지를 치켜세웠습니다. "정확해요.

이제 다음 단계인 Permission 시스템을 더 자세히 알아볼까요?"

실전 팁

💡 - 개발 환경과 프로덕션 환경의 에이전트 설정을 분리해서 관리하세요

• 새로운 에이전트를 만들 때는 최소 권한 원칙을 적용하여 필요한 권한만 부여하세요

---

4. Permission 시스템

박시니어 씨가 화이트보드에 세 개의 단어를 크게 적었습니다. "allow, ask, deny.

이 세 가지가 Permission 시스템의 핵심이에요." 김개발 씨는 이 간단해 보이는 세 단어가 어떻게 복잡한 권한 관리를 가능하게 하는지 궁금해졌습니다.

Permission 시스템은 에이전트의 행동을 세 가지 수준으로 제어합니다. allow는 즉시 허용, ask는 사용자 확인 후 허용, deny는 완전 차단입니다.

마치 공항 보안 검색대에서 물품을 반입 가능, 신고 후 반입 가능, 반입 불가로 분류하는 것과 같습니다.

다음 코드를 살펴봅시다.

// Permission 타입 정의
type PermissionLevel = 'allow' | 'ask' | 'deny';

// Permission 규칙 인터페이스
interface PermissionRule {
  action: string;           // 수행할 작업
  target: string;           // 대상 (파일 경로, URL 등)
  level: PermissionLevel;   // 권한 수준
  reason?: string;          // 규칙 설명 (선택)
}

// Permission 설정 예시
const permissionConfig: PermissionRule[] = [
  { action: 'read', target: 'src/**', level: 'allow' },
  { action: 'write', target: 'src/**', level: 'ask' },
  { action: 'write', target: '.env*', level: 'deny' },
  { action: 'execute', target: 'npm test', level: 'allow' },
  { action: 'execute', target: 'rm -rf *', level: 'deny' }
];

김개발 씨는 에이전트 설정에 대해 배웠습니다. 이제 박시니어 씨가 Permission 시스템의 핵심으로 들어갔습니다.

화이트보드에 세 개의 단어가 선명하게 적혀 있습니다. allow, ask, deny.

"이 세 가지면 충분해요?" 김개발 씨가 의아하다는 듯 물었습니다. 박시니어 씨가 설명을 시작했습니다.

"생각해 보세요. 우리가 누군가에게 뭔가를 부탁할 때, 결국 세 가지 답만 있잖아요.

'해도 돼', '물어보고 해', '안 돼'. Permission 시스템도 똑같아요." 쉽게 비유하자면, 이것은 마치 부모가 아이에게 설정하는 규칙과 같습니다.

"간식은 마음대로 먹어도 돼(allow)", "게임은 엄마한테 먼저 물어봐(ask)", "칼은 절대 만지면 안 돼(deny)". 단순하지만 효과적인 규칙 체계입니다.

allow는 즉시 허용입니다. 에이전트가 이 작업을 수행해도 된다고 미리 허락해 놓는 것입니다.

소스 코드를 읽거나 테스트를 실행하는 것처럼 안전한 작업에 적용합니다. 매번 확인을 받을 필요가 없으니 작업 흐름이 끊기지 않습니다.

ask는 사용자 확인 후 허용입니다. 에이전트가 작업을 수행하기 전에 사용자에게 "이 작업을 해도 될까요?"라고 물어봅니다.

코드를 수정하거나 외부 API를 호출하는 것처럼 영향력이 있지만 때로는 필요한 작업에 적용합니다. 사용자가 상황을 보고 판단할 수 있습니다.

deny는 완전 차단입니다. 어떤 상황에서도 이 작업은 수행할 수 없습니다.

환경 변수 파일을 수정하거나 시스템 파일을 삭제하는 것처럼 위험한 작업에 적용합니다. 에이전트가 아무리 필요하다고 해도 이 규칙을 우회할 수 없습니다.

코드를 살펴보면 PermissionRule 인터페이스가 있습니다. 각 규칙은 action(무슨 작업인지), target(어디에 대한 건지), level(어떤 수준인지)을 정의합니다.

예시 설정을 보세요. src 폴더의 파일을 읽는 것은 allow, 수정하는 것은 ask입니다.

읽기는 안전하니까 바로 허용하고, 수정은 확인을 받겠다는 뜻입니다. 하지만 .env 파일 수정은 deny입니다.

환경 변수에는 비밀번호 같은 민감한 정보가 있을 수 있으니까요. 실행 권한도 마찬가지입니다.

npm test는 안전한 명령이니 allow, 하지만 rm -rf *는 모든 파일을 삭제하는 위험한 명령이니 deny입니다. target에서 **나 * 같은 패턴을 사용할 수 있다는 점도 주목하세요.

일일이 모든 파일을 나열하지 않아도 규칙을 정의할 수 있습니다. 김개발 씨가 깨달음을 얻은 표정으로 말했습니다.

"아, 그래서 아까 에이전트가 제 코드를 수정하기 전에 확인을 요청했군요!" 박시니어 씨가 미소 지었습니다. "맞아요.

ask 권한이 설정되어 있었거든요."

실전 팁

💡 - 새로운 프로젝트를 시작할 때 기본 Permission 규칙 세트를 먼저 정의하세요

• deny 규칙은 신중하게 설정하되, 보안에 관련된 부분은 절대 양보하지 마세요

---

5. 에이전트별 도구 제한

"그런데 궁금한 게 있어요." 김개발 씨가 손을 들었습니다. "아까 build 에이전트는 write 도구가 있고, explore 에이전트는 없다고 하셨잖아요.

이건 Permission과는 다른 건가요?" 박시니어 씨가 고개를 끄덕였습니다. "좋은 질문이에요.

이건 도구 제한이라는 또 다른 보안 레이어예요."

도구 제한은 에이전트가 사용할 수 있는 도구 자체를 제한하는 것입니다. Permission이 "이 도구로 무엇을 할 수 있는가"를 제어한다면, 도구 제한은 "이 도구를 사용할 수 있는가"를 제어합니다.

마치 주방에서 요리사에게 칼을 줄지 말지를 결정하는 것과 같습니다.

다음 코드를 살펴봅시다.

// 에이전트별 도구 제한 설정
interface ToolRestriction {
  agentType: string;
  allowedTools: string[];
  deniedTools: string[];
}

const toolRestrictions: ToolRestriction[] = [
  {
    agentType: 'explore',
    allowedTools: ['read', 'glob', 'grep', 'webSearch'],
    deniedTools: ['write', 'edit', 'bash', 'execute']
  },
  {
    agentType: 'build',
    allowedTools: ['read', 'write', 'edit', 'bash', 'glob'],
    deniedTools: ['webSearch', 'webFetch']
  },
  {
    agentType: 'plan',
    allowedTools: ['read', 'glob', 'grep'],
    deniedTools: ['write', 'edit', 'bash', 'execute']
  }
];

// 도구 사용 가능 여부 확인
function canUseTool(agent: Agent, toolName: string): boolean {
  const restriction = toolRestrictions.find(r => r.agentType === agent.type);
  return restriction?.allowedTools.includes(toolName) ?? false;
}

김개발 씨는 Permission 시스템까지 이해했습니다. 하지만 아까 본 코드에서 에이전트마다 tools 목록이 다른 것이 계속 신경 쓰였습니다.

이것도 Permission의 일부인가요? 박시니어 씨가 설명했습니다.

"아니요, 이건 도구 제한이라는 별개의 시스템이에요. Permission과 함께 이중 보안을 제공하죠." 쉽게 비유하자면, 이것은 마치 직업에 따른 도구 지급과 같습니다.

의사에게는 청진기와 수술 도구를 주고, 요리사에게는 칼과 후라이팬을 줍니다. 의사가 아무리 요리를 잘해도 병원에서는 후라이팬을 쓸 일이 없습니다.

에이전트도 마찬가지로, 자신의 역할에 필요한 도구만 가지고 있습니다. Permission과 도구 제한의 차이를 명확히 해봅시다.

Permission은 "칼로 무엇을 자를 수 있는가"를 제어합니다. 이 칼로 당근은 잘라도 되지만(allow), 케이크는 물어보고 자르고(ask), 손은 절대 안 됩니다(deny).

도구 제한은 "칼을 가질 수 있는가"를 제어합니다. 애초에 칼이 없으면 무엇을 자를지 고민할 필요도 없습니다.

탐색 전용 에이전트에게는 칼 자체를 주지 않습니다. 코드를 살펴보면 ToolRestriction 인터페이스가 있습니다.

각 에이전트 타입에 대해 허용된 도구 목록(allowedTools)과 금지된 도구 목록(deniedTools)을 정의합니다. explore 에이전트를 보세요.

read, glob, grep, webSearch만 허용됩니다. 코드를 읽고 검색하는 도구만 있습니다.

write, edit, bash, execute는 금지됩니다. 코드를 탐색하는 역할이니까 수정하는 도구는 필요 없습니다.

build 에이전트는 다릅니다. read, write, edit, bash, glob이 허용됩니다.

코드를 생성하고 수정해야 하니까요. 하지만 webSearch와 webFetch는 금지됩니다.

외부 정보를 가져오는 건 explore 에이전트의 역할이니까요. canUseTool 함수를 보세요.

에이전트가 특정 도구를 사용하려 할 때 이 함수가 호출됩니다. 해당 에이전트 타입의 allowedTools 목록에 그 도구가 있는지 확인합니다.

없으면 false를 반환하고, 도구 사용이 거부됩니다. 이렇게 이중 레이어로 보안을 구성하면 어떤 이점이 있을까요?

첫째, 역할 분리가 명확해집니다. 각 에이전트가 자기 역할에 집중하고, 다른 역할을 침범하지 않습니다.

둘째, 실수 방지가 됩니다. 탐색만 하려던 에이전트가 실수로 파일을 수정하는 일이 없습니다.

셋째, 감사 추적이 쉬워집니다. 어떤 변경이 발생했을 때 어느 에이전트가 한 건지 바로 알 수 있습니다.

김개발 씨가 정리해서 말했습니다. "그러니까 Permission은 '이 작업을 해도 되느냐'이고, 도구 제한은 '이 도구를 가지고 있느냐'인 거네요?" 박시니어 씨가 박수를 쳤습니다.

"완벽해요!"

실전 팁

💡 - 새로운 에이전트를 만들 때는 필요한 최소한의 도구만 허용하세요

• 도구 제한과 Permission을 함께 사용해서 다층 보안을 구축하세요

---

6. 커스텀 에이전트 정의하기

"이제 마지막으로 제일 재미있는 부분이에요." 박시니어 씨가 눈을 반짝이며 말했습니다. "지금까지 배운 것들을 활용해서 나만의 에이전트를 만들 수 있어요." 김개발 씨의 눈이 휘둥그레졌습니다.

"제가 직접 에이전트를 만들 수 있다고요?"

커스텀 에이전트는 특정 업무에 맞게 직접 정의하는 에이전트입니다. 빌트인 에이전트로 해결되지 않는 특수한 요구사항이 있을 때 사용합니다.

네임스페이스, 설정, 권한, 도구 제한을 모두 조합해서 원하는 대로 에이전트를 설계할 수 있습니다.

다음 코드를 살펴봅시다.

// 커스텀 에이전트 정의
const codeReviewAgent: AgentDefinition = {
  name: 'Code Review Agent',
  description: '코드 리뷰 전문 에이전트',
  model: 'sonnet',

  // 사용 가능한 도구
  tools: ['read', 'glob', 'grep'],

  // 권한 설정
  permissions: [
    { action: 'read', target: '**/*', level: 'allow' },
    { action: 'write', target: '**/*', level: 'deny' }
  ],

  // 시스템 프롬프트
  systemPrompt: `
    당신은 코드 리뷰 전문가입니다.
    코드의 품질, 가독성, 성능을 분석하고 개선점을 제안합니다.
    코드를 직접 수정하지 않고 리뷰 의견만 제공합니다.
  `,

  // 출력 형식
  outputFormat: 'markdown'
};

// 에이전트 등록
Agent.register(codeReviewAgent);

김개발 씨는 지금까지 배운 모든 것이 이 순간을 위한 것이었다는 걸 깨달았습니다. 네임스페이스, 빌트인 에이전트, 설정, 권한, 도구 제한.

이 모든 개념을 조합하면 자신만의 에이전트를 만들 수 있습니다. 박시니어 씨가 예를 들어 설명했습니다.

"우리 팀에 코드 리뷰를 전담하는 에이전트가 있으면 어떨까요?" 쉽게 비유하자면, 커스텀 에이전트를 만드는 것은 마치 로봇을 조립하는 것과 같습니다. 머리(모델)를 선택하고, 팔(도구)을 붙이고, 행동 규칙(권한)을 프로그래밍하고, 임무(시스템 프롬프트)를 부여합니다.

같은 부품이라도 어떻게 조합하느냐에 따라 전혀 다른 로봇이 됩니다. 코드 리뷰 에이전트의 정의를 하나씩 살펴봅시다.

먼저 기본 정보입니다. name과 description으로 에이전트가 무엇인지 설명합니다.

model은 sonnet을 선택했습니다. 코드 리뷰는 깊은 분석이 필요하지만 opus만큼의 비용을 들일 필요는 없다고 판단했습니다.

다음은 도구 설정입니다. read, glob, grep만 허용했습니다.

코드 리뷰 에이전트는 코드를 읽고 분석만 하면 됩니다. 수정하는 건 다른 에이전트나 개발자의 몫입니다.

권한 설정을 보세요. 모든 파일 읽기는 allow, 모든 파일 쓰기는 deny입니다.

이렇게 하면 에이전트가 실수로라도 코드를 수정할 수 없습니다. 리뷰만 하고, 수정은 하지 않는다는 원칙을 기술적으로 강제한 것입니다.

시스템 프롬프트가 핵심입니다. 에이전트의 성격과 임무를 자연어로 정의합니다.

"코드 리뷰 전문가"라는 역할, "품질, 가독성, 성능 분석"이라는 임무, "직접 수정하지 않는다"는 제약을 명시했습니다. 마지막으로 outputFormat입니다.

리뷰 결과를 마크다운 형식으로 출력하도록 했습니다. 깔끔하게 정리된 리뷰 문서를 받을 수 있습니다.

그렇다면 이 커스텀 에이전트를 어떻게 등록하고 사용할까요? Agent.register 함수로 시스템에 등록합니다.

등록된 에이전트는 다른 빌트인 에이전트처럼 사용할 수 있습니다. 팀원 누구나 "코드 리뷰해 줘"라고 요청하면 이 에이전트가 동작합니다.

실무에서 커스텀 에이전트는 다양하게 활용됩니다. 문서 작성 전문 에이전트, 테스트 코드 생성 에이전트, 보안 취약점 검사 에이전트 등을 만들 수 있습니다.

각 팀의 필요에 맞게 특화된 에이전트를 설계하면 됩니다. 주의할 점이 있습니다.

커스텀 에이전트가 너무 많아지면 관리가 어려워집니다. 정말 필요한 경우에만 새 에이전트를 만들고, 비슷한 역할은 기존 에이전트를 확장하는 것이 좋습니다.

김개발 씨가 흥분해서 말했습니다. "우리 팀에 딱 맞는 에이전트를 만들어 볼게요!" 박시니어 씨가 웃으며 대답했습니다.

"좋아요. 하지만 먼저 팀원들과 상의해서 정말 필요한지 확인하고, 권한 설정은 꼭 검토받으세요.

보안은 아무리 강조해도 지나치지 않으니까요."

실전 팁

💡 - 커스텀 에이전트를 만들기 전에 빌트인 에이전트로 해결할 수 있는지 먼저 검토하세요

• 시스템 프롬프트는 명확하고 구체적으로 작성해야 에이전트가 의도대로 동작합니다

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!