헤드리스 AI의 개념과 특징: AI 에이전트 활용하기

헤드리스 AI는 대화 화면 없이 실행합니다

매주 월요일에 지난주 메모를 읽고 이번 주 할 일 초안을 만들어 두고 싶다고 해 봅시다. 매번 채팅창에 메모를 붙여 넣는 대신, 프로그램이 메모를 AI에 넘기고 결과를 파일로 저장하게 만들 수 있습니다. 이렇게 대화 화면을 열지 않고 AI 작업을 실행하는 방식을 헤드리스(headless) AI라고 부릅니다.

이 흐름에서 사람은 대화창에 아무것도 입력하지 않습니다. 사람이 터미널에서 명령을 직접 입력해 한 번 실행해도, 대화 화면을 거치지 않았다면 헤드리스입니다. 결과를 화면에서 읽거나 파일을 열어 보는 일은 사람이 해도 됩니다.

주문 뒤 결제 알림이 오는 것처럼 화면 뒤에서 프로그램이 일하는 방식은 이미 흔합니다. 알림 전송에는 AI가 필요 없지만, 문장을 요약하거나 문의 내용을 분류하는 일에는 AI가 필요합니다. 이런 일을 비대화형 프로그램에 넣으면 헤드리스 AI가 됩니다.

여기서 두 말을 구분합니다. 비대화형 실행은 사람이 대화창에서 매번 응답하지 않아도 입력을 받아 작업하도록 만든 방식이고, 예약 실행은 정해진 시각에 그 작업을 다시 시작하게 하는 방식입니다. 명령을 한 번 성공시켰다고 다음 날 같은 시각에 다시 실행되지는 않습니다. 반복하려면 예약을 따로 만들어야 합니다.

채팅, 헤드리스, 에이전트는 어떻게 연결될까요?

채팅에서는 사람이 답을 읽고 다음 요청을 입력합니다. 헤드리스에서는 요청과 자료를 미리 넘기고 결과를 돌려받습니다. 받은 결과를 사람이 검토하게 할 수도 있고, 검사를 통과한 결과만 다음 프로그램으로 넘길 수도 있습니다.

AI 에이전트는 도구를 쓰며 다음 행동을 스스로 정해 작업하는 시스템입니다. 헤드리스는 실행 방식이고 에이전트는 일하는 방식이라 둘은 별개로 정해집니다. 대화 화면 안에서 도는 에이전트도 있고, 에이전트가 아닌 헤드리스 호출도 있습니다.

작업 예별 헤드리스와 에이전트 여부

작업 예	헤드리스대화 화면 없이 실행	에이전트도구를 쓰며 다음 행동 결정
채팅창에 메모를 붙여 넣고 요약 요청	제공하지 않음	제공하지 않음
터미널 명령 한 줄로 메모 요약	제공	제공하지 않음
대화창에서 AI가 파일을 열고 고치며 작업	제공하지 않음	제공
예약 프로그램이 AI에게 도구를 주고 작업을 맡김	제공	제공

헤드리스 브라우저는 이름이 같지만 다른 개념입니다. 브라우저 창을 띄우지 않고 웹페이지를 처리하는 프로그램이며, AI 작업이 이 브라우저를 도구로 쓸 수는 있습니다.

에이전트가 작업을 반복하는 과정

앤트로픽은 Claude Agent SDK 소개 글에서 에이전트가 맥락 수집, 행동, 결과 확인을 되풀이한다고 설명합니다. SDK는 개발자가 프로그램에 기능을 연결할 때 쓰는 도구 모음입니다.

그림의 Gather context는 필요한 정보 수집, Take action은 작업 실행, Verify work는 결과 확인입니다. 확인에서 부족한 점이 나오면 다시 정보를 모으고 작업합니다. 이 반복이 끝없이 돌지 않도록 성공 조건과 함께 시간, 비용, 재시도 횟수로 멈출 조건을 정해 둡니다.

헤드리스에서는 단계마다 사람이 답을 바로 읽지 않는 경우가 많습니다. 그래서 잘못된 결과가 다음 단계로 넘어가지 않게 검사를 넣고, 어떤 경우에 사람에게 검토를 넘길지도 미리 정합니다.

이메일 분류 예시에서 AI가 맡는 부분

다음은 앤트로픽 글에 실린 이메일 처리 코드 그림입니다. 고객 메일인지는 일반 코드로 구별하고, 긴급한지는 AI에 물은 뒤 담당자에게 전달하는 흐름입니다.

그림의 코드는 흐름을 보여 주는 예시라 그대로는 실행되지 않습니다. AI 응답을 담는 변수는 isEmailUrgent인데 아래 조건문은 isUrgent를 쓰므로 이름부터 맞춰야 하고, 메일을 가져오고 전달하는 함수도 따로 만들어야 합니다. 발신 주소에 특정 문자열이 들어 있는지만 보는 것으로는 고객의 신원을 검증할 수 없습니다.

이 그림에서 가져올 것은 정해진 절차는 코드가, 판단은 AI가 맡는다는 나눔입니다. 실제 문의함에 붙인다면 처음부터 고객에게 자동으로 답장하지 않고, AI가 문의마다 분류를 붙인 목록을 만들어 담당자가 원문과 함께 보게 합니다. 처음에는 아래처럼 분류 세 가지면 충분합니다.

문의 세 건에 붙는 분류

받은 문의	긴급 후보지금 이용이 막힘	일반일반 질문	확인 필요판단할 정보 부족
오늘부터 계정에 로그인할 수 없습니다	제공	제공하지 않음	제공하지 않음
요금제에 어떤 기능이 포함되나요?	제공하지 않음	제공	제공하지 않음
문제가 있습니다	제공하지 않음	제공하지 않음	제공

세 번째처럼 정보가 부족한 문의를 일반으로 넘기면 급한 문의가 묻힐 수 있습니다. 그래서 자료에 없는 원인을 AI가 추측하지 말고 '확인 필요'로 남기라고 요청 문장에 적습니다. 결과 목록의 문의 건수가 받은 문의 건수와 같은지 대조하는 검사도 코드로 붙입니다.

주간 리포트도 같은 방식으로 나눕니다. 예약 프로그램은 자료를 가져오고, AI는 요약 초안을 만들고, 별도 검사가 날짜와 수치를 원자료와 대조합니다. 결과 파일을 만드는 일과 슬랙이나 이메일로 보내는 일은 서로 다른 작업이라, 초안이 완성됐다고 발송까지 끝난 것은 아닙니다.

Claude Code로 한 번 실행하는 명령

Claude Code는 앤트로픽이 만든 터미널용 AI 코딩 도구이고, 대화 화면 없이 명령 한 줄로 결과만 받는 실행도 지원합니다. 명령을 입력하는 창이 터미널입니다. Mac에서는 터미널 앱, Windows에서는 PowerShell을 열고 claude --version을 입력해 버전 번호가 나오면 설치된 상태입니다. 명령을 찾을 수 없다고 나오면 Claude Code 설치 안내부터 진행합니다.

작업할 폴더로 이동한 뒤 다음 한 줄을 실행하면, Claude Code가 명령 안에 적은 메모를 한 줄로 요약합니다.

터미널, Claude Code 비대화형 실행

> claude --bare --tools="" -p "다음 메모를 한 줄로 요약해 주세요. 금요일 오후 3시 거래처 미팅. 준비물은 견적서와 노트북."

금요일 오후 3시 거래처 미팅에 견적서와 노트북을 챙깁니다.

요일, 시각, 장소, 준비물이 모두 남았는지 봅니다

결과를 출력하고 다시 명령 입력 상태로 돌아옴

-p는 대화 화면 대신 결과를 출력하는 옵션입니다. --tools=""는 내장 도구를 모두 끄고, --bare는 프로젝트의 지침 파일과 훅, 플러그인을 자동으로 찾아 읽는 과정을 건너뜁니다. 그래서 --bare 없이 -p만 쓰면 그 폴더의 프로젝트 설정이 결과에 섞일 수 있습니다. 옵션 설명은 Claude Code 비대화형 실행 문서에 있습니다.

bare 모드는 구독 로그인 인증을 쓰지 않습니다. 환경 변수에 ANTHROPIC_API_KEY가 설정되어 있어야 하고, 실행할 때마다 설정한 모델의 API 사용료가 나갑니다. 키는 요청 문장이나 명령 인자에 붙여 넣지 않습니다.

결과가 출력되고 다시 명령을 입력할 수 있는 상태로 돌아오면 실행 한 번이 끝난 것입니다. 오류 문구를 출력하고 끝나는 경우도 있으므로, 끝났다는 사실보다 출력 내용을 봅니다. 오래 기다려도 끝나지 않으면 Ctrl+C로 멈춥니다. 인증 오류나 알 수 없는 옵션 오류가 나면 같은 명령을 반복하지 말고 버전과 오류 문구를 공식 문서와 대조합니다. 도움을 요청할 때는 키를 뺀 명령과 오류만 전달합니다.

다른 프로그램에 연결할 때 구별할 옵션

--output-format json은 결과와 관련 정보를 프로그램이 읽기 쉬운 JSON 형식으로 출력합니다. JSON은 항목 이름과 값을 짝지어 담는 데이터 형식입니다. 형식이 맞게 나와도 요약 내용이 정확한지는 별도 검사로 봅니다.

이름이 닮아 혼동하기 쉬운 옵션이 --tools와 --allowedTools입니다. --tools는 쓸 수 있는 도구의 범위를 줄이고, --allowedTools는 확인 질문을 건너뛰게 합니다.

도구 옵션 두 가지가 하는 일

하는 일	--tools도구 목록 지정	--allowedTools자동 승인 지정
쓸 수 있는 내장 도구를 목록으로 줄인다	제공	제공하지 않음
지정한 도구를 확인 질문 없이 실행한다	제공하지 않음	제공

그래서 --allowedTools Read라고만 적으면 Read를 묻지 않고 실행하게 될 뿐, 다른 도구의 권한이 사라지지는 않습니다. 옵션 전체 목록은 Claude Code 명령어 참조에 있습니다.

결과를 파일에 저장하거나 GitHub Actions 같은 실행 서비스에 연결하려면 출력 경로와 계정 인증, 일정, 실패 처리까지 구성해야 합니다. 셸에서 >로 결과를 파일에 저장하면 같은 이름의 기존 파일을 덮어씁니다. 처음 파일 저장을 연결할 때는 새 파일 이름을 씁니다.

반복 실행을 맡기기 전에 정할 것

반복 업무와 연결할 때는 먼저 언제 시작할지를 정합니다. 시작 조건은 대표적으로 네 가지입니다.

• 일정: 매주 월요일 오전 9시처럼 시각을 정하고, 어느 지역의 시간인지도 함께 정합니다.
• 웹훅(Webhook): 문의 접수처럼 외부 서비스가 보낸 알림을 받으면 실행합니다.
• 데이터 변화: 새 파일이나 새 행을 감지한 프로그램이 작업을 시작합니다.
• 다른 프로그램의 호출: 앞 단계가 끝나면 다음 작업을 시작합니다.

일정만 적어 둔다고 자동화가 계속 돌지는 않습니다. 예약을 실행할 컴퓨터나 서버가 켜져 있어야 하고, 그 환경이 필요한 자료와 계정에 접근할 수 있어야 합니다. 자료 한 건이 맞게 처리됐다면 빈 자료와 애매한 자료도 넣어 본 뒤, 아래 순서로 운영 조건을 정합니다.

AI에게 "예산 안에서 해 줘"라고 요청해도 비용을 막는 장치가 생기지는 않습니다. 비용 한도는 실행 프로그램이나 서비스 설정에 적어야 하고, 사용량을 알려 주기만 하는 기능과 실제로 실행을 멈추는 기능도 서로 다릅니다.

처음에는 결과 파일을 만들고 사람이 확인하는 데서 끝냅니다. 같은 작업이 여러 번 맞게 나온 뒤에 발송이나 다음 프로그램 호출을 연결합니다.

자주 묻는 질문

컴퓨터를 꺼도 실행되나요?

내 컴퓨터가 실행을 맡는다면 꺼져 있을 때는 작업이 시작되지 않습니다. 별도 서버나 실행 서비스에서 돌도록 구성했다면 그 환경에서 실행됩니다. 헤드리스라는 말에 클라우드 실행이 포함되지는 않습니다.

코딩을 몰라도 만들 수 있나요?

AI에게 구성을 도와 달라고 요청할 수 있습니다. 다만 파일이 만들어졌다고 연결과 예약까지 끝난 것은 아니므로, 어떤 자료를 읽고 어디에 결과를 남기는지 설명할 수 있어야 하고 시험 실행과 실패 처리도 직접 봐야 합니다. 입력 자료와 기대 결과를 정하는 것부터 시작합니다.

사람이 승인하는 단계가 있어도 헤드리스인가요?

그렇습니다. AI가 대화 화면 없이 초안을 만들고, 다른 화면에서 사람이 승인한 뒤 다음 프로그램이 발송하도록 구성할 수 있습니다. 비대화형 실행과 사람의 검토는 함께 쓸 수 있습니다.