AI 에이전트 빌더

이 페이지는 DevUtilities AI 에이전트 빌더로 LLM 에이전트를 구축하기 위한 정식 가이드입니다. 읽는 동안 위의 안내 워크플로를 사용하거나 아래 주제로 이동하세요. Schemas, MCP JSON, 프롬프트, 토큰 수는 브라우저에 머물며 추론을 위해 업로드되지 않습니다.

AI 에이전트 빌더는 프로덕션용 에이전트 설정을 조립하는 클라이언트 측 워크숍입니다. OpenAI function calling용 JSON Schema 도구, Cursor와 Claude Desktop용 mcpServers 검증, system prompts, 합산 토큰 예산, 팀 인수인계용 내보내기 산출물을 다룹니다.

얻는 것

• 네 가지 워크플로 모드: 전체 에이전트, function calling만, MCP 설정, 구조화 응답
• 스타터 템플릿: Filesystem MCP, OpenAI function calling, 구조화 분류기
• 예제 JSON → JSON Schema 추론(선택적 엄격 additionalProperties: false)
• JSON-pointer 오류·경고가 있는 로컬 MCP lint
• 프롬프트, minify된 tools, MCP JSON을 합친 토큰 예산
• 내보내기: OpenAI tools JSON, response_format, MCP 설정, markdown 요약, 전체 번들

이 빌더를 사용할 때

• OpenAI tools JSON이 필요하고 JSON Schema를 손으로 쓰고 싶지 않을 때
• Cursor 또는 Claude Desktop MCP 서버를 연결하고 붙여넣기 전에 lint가 필요할 때
• 에이전트의 prompt + tools가 컨텍스트 창에 맞는지 증명해야 할 때
• schema → MCP → prompt → export를 잇는 지속 세션이 필요할 때

독립 도구를 선호할 때

• 깊은 인코딩 비교나 비용 계산만 필요 → LLM Token Counter
• 프롬프트 없는 일회성 MCP lint만 필요 → MCP Validator
• 샘플에서 스키마 추론만 필요 → Structured Output Generator

도구를 정의하기 전에 모드를 선택하세요. 모드는 관련 없는 단계를 숨겨 빈 패널과 싸우지 않게 합니다.

전체 에이전트용 첫 안내입니다. 템플릿 단축키는 이 단계 중 일부를 건너뜁니다.

1. 전체 에이전트를 선택하거나 OpenAI function calling 템플릿을 불러옵니다.
2. 도구 정의에서 명확한 이름, 설명, 대표 예제 JSON 인수로 각 도구를 추가합니다.
3. 추론된 JSON Schema를 검토하고 OpenAI structured outputs / strict tool calling용 엄격 모드를 켭니다.
4. 에이전트가 Cursor 또는 Claude Desktop에서 실행되면 mcpServers JSON을 붙여넣거나 편집하고, 계속하기 전에 모든 오류를 고칩니다.
5. 어떤 도구를 언제 호출하고 무엇을 절대 지어내지 말지 모델에 알려 주는 system instructions를 작성합니다.
6. 토큰 예산을 열고 cl100k_base 또는 o200k_base를 선택한 뒤 합계가 모델에 맞는지 확인합니다.
7. API용 OpenAI tools JSON, 데스크톱 클라이언트용 MCP 설정, 팀용 markdown 요약을 내보냅니다.
8. 선택적으로 전체 번들 JSON을 내보내 다른 엔지니어가 나중에 같은 세션 상태를 다시 불러올 수 있게 합니다.

문제: OpenAI function calling으로 날씨와 주문을 조회하는 고객 지원 에이전트가 필요하지만, 손으로 쓴 JSON Schema가 엄격 검증에 계속 실패합니다.

이 도구로 해결하는 방법

1. Function calling 모드를 선택하거나 OpenAI function calling 템플릿(날씨 + 주문 조회)을 불러옵니다.
2. 프로덕션에 필요한 모든 필드가 최소 한 번 나오도록 예제 JSON을 편집합니다 — 빠진 키는 required 속성이 되지 않습니다.
3. 엄격 모드를 켜 모든 객체가 additionalProperties: false를 내도록 합니다.
4. system prompt를 조입니다: 주문 ID 확인, 도구 결과 날조 금지, 답변 간결 유지.
5. GPT-4o에 배포한다면 o200k_base로 토큰 예산을 확인합니다.
6. OpenAI tools JSON을 내보내 Chat Completions 또는 Responses API 클라이언트에 붙여넣습니다.

결과: API 준비된 엄격 tools 배열과 스키마에 맞는 프롬프트 — 별도 스키마 편집기 불필요.

문제: Cursor 또는 Claude Desktop이 mcp.json을 거부하거나, 파일시스템 서버가 잘못된 디렉터리로 시작해 디스크를 너무 많이 봅니다.

이 도구로 해결하는 방법

1. MCP 설정 모드를 선택하거나 Filesystem MCP 템플릿을 불러옵니다.
2. /path/to/allowed/dir를 에이전트가 만질 수 있는 유일한 디렉터리의 절대 경로로 바꿉니다.
3. 검증을 실행하고 누락된 command/args, 잘못된 URL, 문자열이 아닌 env 값을 고칩니다.
4. 브라우저에서 lint하는 동안 플레이스홀더 env 값(프로덕션 비밀 아님)을 사용합니다.
5. 검증된 mcpServers JSON을 Cursor 또는 Claude Desktop 설정으로 내보냅니다.
6. 파괴적 파일 작업 전 확인을 요구하는 system instructions를 추가합니다.

결과: lint된 MCP 클라이언트 설정과, 데스크톱 앱을 재시작하기 전에 서버 능력과 맞는 프롬프트.

문제: 모델이 감정, 신뢰도, 주제, 짧은 요약을 JSON으로 반환해야 합니다 — 자유 형식 답변은 다운스트림 파서를 깨뜨립니다.

이 도구로 해결하는 방법

1. 구조화 응답 모드를 선택하거나 구조화 분류기 템플릿을 불러옵니다.
2. 파이프라인이 기대하는 정확한 형태에 맞게 예제 JSON을 편집합니다.
3. 엄격 모드를 켜 선언되지 않은 키가 검증 시 거부되게 합니다.
4. JSON 객체 밖의 산문을 금지하는 system prompt를 작성합니다.
5. OpenAI structured outputs용 response_format json_schema를 내보냅니다.
6. 분류할 입력 문서를 위한 여유가 토큰 예산에 남는지 확인합니다.

결과: 일치하는 지시와 함께 structured-output API에 넣을 수 있는 단일 출력 스키마.

문제: 도구 세 개와 긴 MCP 설정을 추가한 뒤, 채팅 기록을 포함하면 에이전트 합산 프롬프트가 GPT-4o의 실용 예산에 맞지 않습니다.

이 도구로 해결하는 방법

1. 토큰 예산 단계를 열고 prompt + minify된 tools + MCP JSON 합계를 기록합니다.
2. 도구 설명을 줄이고 required 스키마를 부풀리는 미사용 예제 필드를 제거합니다.
3. 항상 켜진 system prompt의 장황한 정책 문구를 온디맨드 검색으로 옮깁니다.
4. 더 깊은 인코딩 계산만 필요하면 조립된 페이로드를 LLM Token Counter로 복사합니다.
5. 기록과 completions용 여유가 예산에 보일 때만 다시 내보냅니다.

결과: 프로덕션 첫 400 오류 이후가 아니라 빌더에서 초과를 잡습니다.

예제 JSON은 엄격한 JSON이어야 합니다. 예제에 있는 키만 required 속성이 됩니다. 중첩 객체와 배열은 샘플 값에서 타입을 추론합니다.

실무 규칙

• 모델이 보낼 수 있어야 하는 모든 필드를 포함하세요 — 생략은 “required 아님”이지 “default가 있는 선택”이 아닙니다.
• 현실적인 enum을 문자열 샘플로 쓰고, 명시적 enum 배열이 필요하면 스키마를 손으로 편집하세요.
• 엄격 모드를 켜 모든 객체에 additionalProperties: false를 내세요 — OpenAI structured outputs와 strict tool calling에 권장됩니다.
• 빈 배열은 약한 item 타입을 추론합니다 — 대표 요소를 하나 이상 추가하세요.

Stdio 서버에는 command와 보통 args가 필요합니다. 원격 서버에는 유효한 http 또는 https url이 필요합니다. env 값은 문자열이어야 합니다. 오류는 내보내기 신뢰를 막고, 경고는 수동 점검이 필요합니다.

일반적인 클라이언트 엔벨로프

• 최상위 키는 Cursor와 Claude Desktop 관례상 "mcpServers"여야 합니다
• 파일시스템 서버는 절대 경로 allow-list를 사용해야 합니다
• 브라우저 편집 중에는 env 플레이스홀더를 쓰고, 실제 비밀은 로컬 머신에서만 주입하세요

토큰 수는 system prompt, minify된 도구 스키마, MCP JSON을 합칩니다. GPT-4 / Claude 근사에는 cl100k_base, GPT-4o에는 o200k_base를 선택하세요. 카운트는 로컬 tiktoken 테이블을 쓰며 API 호출이 없습니다.

• 숫자를 하한으로 취급하세요: 채팅 기록과 도구 결과는 런타임에 더해집니다
• 스키마나 프롬프트를 편집할 때마다 다시 확인하세요
• 경계 맵이나 맞춤 페이로드의 월간 비용 카드가 필요하면 LLM Token Counter를 사용하세요

증상: OpenAI가 tools 페이로드를 거부하거나, 앱이 실제로 필요한 인수를 모델이 전달하지 못합니다.

원인

엄격 스키마는 선언되지 않은 키를 거부합니다. 예제 JSON에서 필드를 빼면 속성이 되지 않습니다. 엄격 모드가 꺼져 있어도 OpenAI structured-output 제한이 열린 객체를 거부할 수 있습니다.

진단

추론된 스키마 properties와 앱이 보내는 인수를 비교하세요. OpenAI structured outputs를 목표로 할 때 엄격 모드가 켜져 있는지 확인하세요.

수정

1. 빠진 키를 예제 JSON에 추가하고 스키마를 다시 생성하세요.
2. 중첩 객체 전반에 additionalProperties: false가 일관되도록 엄격 모드를 켜세요.
3. OpenAI structured output 제한에 맞게 깊게 중첩된 oneOf, 특이한 타입 등 미지원 구성을 줄이세요.
4. tools JSON을 다시 내보내고 알려진 올바른 인수 페이로드로 재테스트하세요.

증상: command/url 검증 오류, 클라이언트가 서버를 시작하지 못함, 원격 전송이 연결되지 않음.

원인

command 없는 stdio, http(s) URL 없는 원격, 숫자 env, 잘못된 최상위 키는 클라이언트 파서를 깨뜨립니다.

진단

각 lint 오류의 JSON pointer를 읽으세요. 엔벨로프가 mcpServers를 쓰고 각 서버가 stdio(command) 또는 원격(url)인지, 깨진 하이브리드가 아닌지 확인하세요.

수정

1. stdio 서버에 command와 args를 추가하고 모든 env 값을 문자열로 인용하세요.
2. 원격 MCP 전송에는 http:// 또는 https:// URL을 사용하세요.
3. 최상위 키 이름을 mcpServers로 고치세요.
4. 오류가 없어질 때까지 다시 검증하고, 배포 전에 경고를 정리하세요.

증상: 내보낸 JSON, git diff, 빌더 스크린샷에 API 키가 나타납니다.

원인

MCP env 블록은 일반 JSON입니다. 프로덕션 비밀을 브라우저 도구(로컬이라도)에 붙여넣으면 클립보드, 화면 공유, 실수 커밋으로 유출 위험이 커집니다.

진단

내보내기와 MCP 패널에서 sk-, Bearer, 벤더 키 패턴을 검색하세요. 커밋된 설정에 플레이스홀더만 있는지 확인하세요.

수정

1. 빌더에서 비밀을 ${ENV_VAR} 스타일 플레이스홀더로 바꾸세요.
2. 실제 값은 로컬 데스크톱 클라이언트나 배포 시크릿 스토어에서만 주입하세요.
3. 채팅, 티켓, 공유 화면에 붙여넣은 키는 로테이션하세요.
4. mcp.json과 에이전트 번들용 pre-commit 시크릿 스캔을 추가하세요.

이 워크스페이스는 설정을 업로드하지 않습니다 — 하지만 클립보드와 git은 여전히 유출할 수 있습니다.

• MCP env 블록에 API 키를 커밋하지 마세요 — 환경 변수 플레이스홀더를 사용하세요
• 파일시스템 MCP 서버에는 최소 권한 절대 경로를 사용하세요
• 프로덕션 프롬프트에 큰 few-shot 예제를 넣기 전에 토큰 예산을 검토하세요
• 예상치 못한 키를 tools가 받지 않도록 엄격 스키마를 선호하세요
• 내부 도구 이름이나 인프라 호스트가 있으면 내보낸 번들을 민감하게 취급하세요

• 템플릿에서 시작한 뒤 불필요한 도구를 삭제하세요 — 작은 스키마가 더 싸고 안전합니다
• system prompt 지시와 맞는 명확한 동사로 도구를 이름 지으세요(lookup_order, get_weather)
• 단일 소스를 유지하세요: 갈라진 스키마 사본 대신 이 빌더에서 내보내세요
• 경로나 command를 바꿀 때마다 MCP를 다시 검증하세요
• markdown 내보내기에 토큰 예산을 적어 PR에서 비용 영향을 보이게 하세요
• 깊은 인코딩 diff에는 LLM Token Counter, 조립된 에이전트에는 이 빌더를 사용하세요