에이전트 개요 — 도구 · 액터 · 의도의 3 축

D.Hub 에서 에이전트 는 자연어 입력을 받아 도구 호출 + 결정 의 한 사이클을 자동으로 수행하는 워크플로입니다. 본 레슨은 에이전트의 3 축 과 한 사이클의 5 단계 흐름 을 잡습니다.

에이전트의 3 축

1. 도구 (Tool)

도구는 읽기 · 검색 액션의 표현입니다. 부작용 없이 외부 데이터를 가져오는 호출.

예시:

• get_enriched_order(order_id) — 데이터셋에서 한 행 fetch
• search_refund_policy(query) — 지식 자원에서 임베딩 검색 (RAG)
• query_tactical_zone(zone_name) — 전술 구역 메타데이터 조회

도구는 몇 번을 호출해도 안전 합니다. 같은 입력에 같은 출력 — 결정론적 읽기.

2. 액터 (Actor)

액터는 쓰기 · 행동 액션의 표현입니다. 외부 상태를 바꾸는 호출.

예시:

• issue_refund(order_id, amount) — 환불 API 호출, 실제 금융 거래
• send_rejection_email(customer_id, reason) — 이메일 발송
• log_map_event(user_id, command, output) — 감사 로그 기록
• capture_review_decision(reviewer_id, decision) — 인간 검토자 의 결정 을 받는 액터 (HITL)

액터 호출은 되돌릴 수 없습니다. 한 번 발사된 이메일은 회수가 안 되고, 환불 API 는 완료된 거래 를 만듭니다. 에이전트 설계의 거의 모든 안전 패턴이 액터 호출 직전의 게이트 에 집중됩니다.

3. 의도 분류 (Intent)

의도 분류는 입력 자체를 분류 해 어느 흐름으로 보낼지 결정하는 LLM 호출입니다. 도구나 액터를 호출하기 전에 사용자의 입력을 허용된 카테고리 중 하나로 매핑합니다.

예시 (map_control 의 classify_intent):

• UI_CONTROL — 화면 제어 의도 → 허용
• DATA_QUERY — 데이터 조회 의도 → 차단
• SYSTEM_CONFIG — 시스템 설정 변경 의도 → 차단

의도 분류는 기본 거부 모드입니다 (레슨 5).

한 사이클의 5 단계 흐름

세 축이 묶이는 한 사이클 의 전형 흐름:

1. 사용자 입력 → 의도 분류 — 이 입력이 우리 에이전트의 영역인가? 분류 LLM 한 번.
2. 도구 호출 1–N 회 — 컨텍스트 수집. 데이터셋 fetch · RAG 검색 · 외부 API 조회.
3. LLM 추론 — 수집된 컨텍스트로 권고 또는 응답 생성. 응답 본문에 근거 인용 포함.
4. (HITL) 인간 검토 — 권고를 인간 액터 가 받거나 덮어쓰기. 안전 위험이 큰 흐름에서만.
5. 액터 호출 1–N 회 — 결정을 외부 상태에 반영. 환불 발사 · 이메일 발송 · 좌표 JSON 전송.

각 단계가 서로 분리된 책임 을 갖습니다 — 한 단계의 LLM 오작동이 그 다음 단계의 게이트 에서 잡힐 수 있도록.

실습 시나리오 — 세 갈래의 에이전트

본 코스의 6 레슨은 다음 세 시나리오의 에이전트 패턴을 교대로 참조합니다.

세 시나리오의 zip 을 손에 두면 각 레슨의 예제가 즉시 동작합니다. zip 다운로드 + 적재는 입문 코스 레슨 5 패턴 그대로.

이 레슨에서 익혀야 할 것

• 3 축 — 도구 (Tool) · 액터 (Actor) · 의도 분류 (Intent) — 의 분업
• 한 사이클의 5 단계 흐름 과 각 단계의 책임
• 액터 호출은 되돌릴 수 없다 는 첫 안전 규칙

다음 레슨

도구 한 개를 입출력 스키마 계약 으로 정의합니다.