AI 에이전트를 처음 만들어봤습니다 — 설치보다 오래 걸린 두 가지

AI에이전트를 직접 만들어 돌려봤습니다. AI자동화를 시작하는 데 뭐가 필요한지 궁금하실 텐데, 결론부터 적으면 설치는 금방이고 다른 데서 시간이 갑니다.

1. 실행 도구를 설치합니다 — 수십 분 2. 모델을 연결합니다 — 여기서 막혔습니다 3. 역할과 말투를 파일로 정의합니다 — 반나절 4. 도구 권한을 정합니다 — 제일 중요합니다

에이전트가 뭔가요

간단히 말하면 도구를 쥐여 준 AI입니다. 대화만 하는 것과 다른 점은 여기입니다.

	대화형 AI	에이전트
할 수 있는 것	답을 말합니다	파일을 읽고 쓰고 명령을 실행합니다
결과	화면에 글	실제로 뭔가 바뀝니다
위험	낮습니다	뭘 쥐여 줬느냐에 달렸습니다

마지막 줄이 핵심입니다. 파일을 지울 수 있는 도구를 주면 지울 수도 있습니다.

설치는 어렵지 않았습니다

실행 도구를 깔고 설정 파일을 만드는 데 수십 분 걸렸습니다. 문서대로 따라 하면 됩니다.

여기서 시간을 아끼려고 문서를 건너뛰면 나중에 더 씁니다. 저는 설정 항목의 뜻을 안 읽고 기본값으로 뒀다가, 나중에 왜 이렇게 도는지 몰라서 다시 읽었습니다.

막힌 곳 — 모델 연결

증상 — 설치는 끝났는데 모델을 못 부릅니다. 오류 메시지가 매번 조금씩 달랐습니다.

원인 — 원인이 될 수 있는 게 여럿인데 증상이 비슷했습니다. 순서대로 하나씩 지워야 합니다.

확인	방법
키가 맞나	토큰 발급이 되는지 먼저 봅니다
결제·등급	무료 등급이 잡히는지
모델명이 살아 있나	사용 가능한 모델 목록을 조회해 대조
호출 한도	분당·일일 제한에 걸렸는지

해결 — 저는 세 번째에서 막혔습니다. 예제에 적힌 모델명이 이미 없어진 것이었습니다. 목록을 조회해서 살아 있는 것으로 바꾸니 바로 됐습니다.

available = list_models()          # 먼저 목록부터 받아 본다
print(available)                   # 여기 없는 이름을 쓰고 있었다

모델명을 코드에 그대로 적지 마세요. 목록에서 골라 쓰면 이 문제를 다시 안 겪습니다.

역할은 파일로 둡니다

해결 — 무엇을 하는 사람인지, 무엇은 안 하는지를 문서로 적습니다. 코드에 넣지 않습니다.

roles/
├ writer.md     무엇을 쓰는가 / 무엇은 안 쓰는가 / 말투
└ checker.md    무엇을 확인하는가 / 무엇을 막는가

문서라서 고치기 쉽습니다. 말투가 마음에 안 들면 그 파일만 손보면 됩니다.

설정에서는 이렇게 가리키기만 합니다. 역할이 늘어도 설정은 안 복잡해집니다.

{
  "name": "글쓰기 담당",
  "prompt_file": "roles/writer.md",
  "tools": ["search", "file_read", "file_write"]
}

tools 에 적힌 것이 그 담당의 능력 범위입니다. prompt_file 은 어떻게 할지, tools 는 무엇을 할 수 있는지를 나눠 적는 셈입니다.

주의 — 고친 뒤에는 재시작해야 반영됩니다. 지침은 시작할 때 한 번 읽혀서 메모리에 올라갑니다. 저는 이걸 모르고 "고쳤는데 왜 그대로지" 를 몇 번 반복했습니다.

제일 중요한 것 — 도구 권한

여기를 대충 하면 나중에 사고가 납니다.

에이전트는 가진 도구를 "내가 할 수 있는 일"로 인식합니다. 지침에 "이건 하지 마라" 고 적어도, 도구가 있으면 상황에 따라 씁니다. 지침은 부탁이고 도구는 능력입니다.

원칙	이유
필요한 것만 준다	없으면 시도조차 못 합니다
지우는 도구는 마지막에	되돌리기 어려운 일부터 막습니다
외부로 나가는 것은 승인 뒤에	메일·게시는 취소가 안 됩니다
읽기와 쓰기를 나눈다	읽기만 필요한 일이 많습니다

저는 처음에 편하다고 도구를 다 줬다가, 시키지 않은 일까지 하는 걸 보고 정리했습니다. 처음부터 좁게 주고 필요할 때 늘리는 편이 낫습니다.

특히 되돌리기 어려운 일은 사람 승인을 거치게 두는 게 안전합니다. 메일 발송이나 외부 게시는 한 번 나가면 취소가 안 됩니다.

RISKY = {"mail_send", "publish", "file_delete"}

if tool in RISKY and not approved_by_human:
    raise PermissionError(f"{tool} 은(는) 승인이 필요합니다")

저는 이 목록을 만들기 전에 한 번 겪었습니다. 시키지도 않은 곳에 뭔가 나갈 뻔했는데, 다행히 도구가 없어서 시도만 하고 멈췄습니다.

처음 만들 때 정해 둘 것

정할 것	왜
무엇을 맡길 것인가	범위가 없으면 도구도 못 정합니다
결과를 어디에 남길 것인가	안 남기면 뭘 했는지 모릅니다
실패하면 어떻게 알 것인가	조용히 멈추면 며칠 모릅니다
사람 승인이 필요한 것은 무엇인가	되돌리기 어려운 일 목록

네 번째를 미리 정해 두는 게 좋습니다. 나중에 정하려면 이미 뭔가 나간 뒤입니다.

확인 못 한 것

에이전트 여러 개를 서로 대화시키는 방식이 실제로 쓸 만한지는 확인하지 못했습니다. 하나가 지시하고 다른 하나가 실행하는 구조를 만들어 볼까 했는데, 지금 필요한 일에는 과해 보여서 안 해봤습니다.

간단한 일에는 하나로 충분했습니다. 여럿이 필요한 상황이 어떤 것인지는 아직 모르겠습니다.

판정 — 계속 쓴다

만들어 볼 값어치는 있습니다. 반복되는 일을 맡겨 두면 확실히 손이 덜 갑니다.

설치는 쉽고 나머지가 어렵습니다. 모델 연결과 권한 정하기에서 시간이 갑니다. 이 글의 순서대로 하면 훨씬 빠를 겁니다.

권한을 좁게 주는 것이 제일 중요합니다. 이걸 대충 하면 편한 대신 언젠가 사고가 납니다. 저는 한 번 겪고 나서 전부 정리했습니다.

직접 하실 분께

하나. 모델명을 코드에 박지 마세요. 목록에서 골라 쓰면 연결 문제 절반이 사라집니다.

둘. 역할은 문서 파일로 둡니다. 고치기 쉽고, 나중에 뭘 시켰는지 남습니다.

셋. 도구는 좁게 시작합니다. 늘리는 건 쉽고 줄이는 건 어렵습니다.

넷. 실패했을 때 어떻게 알 것인지 를 만들기 전에 정하세요. 조용히 멈추면 며칠 모릅니다.

다음에는 에이전트를 여럿 두고 서로 일을 넘기는 구조가 실제로 쓸 만한지 해보려고 합니다. 되면 이어서 적겠습니다.