Local AI Agents

Foundry Local과 Qwen으로 로컬 AI 에이전트 만들기

Lesson 17 – 로컬 AI 에이전트 만들기의 동반 스킬입니다. 학습자가 자신의 머신에서 독립적으로 추론하고, 도구를 호출하며, 문서를 검색하는 에이전트를 구축하는 데 사용하세요 — 클라우드 추론 없이. 모든 권장 사항은 수업 내용과 실행 가능한 노트북을 기반으로 합니다.

트리거

학습자가 다음을 원할 때 이 스킬을 활성화하세요:

• 완전히 기기 내에서 에이전트를 실행하여 개인 정보 보호, 비용 절감 또는 오프라인 목적을 달성.
• Foundry Local을 사용하여 로컬에서 모델 서비스를 제공하고 OpenAI 호환 엔드포인트로 연결.
• 신뢰할 수 있는 로컬 도구 호출을 위해 Qwen 함수 호출 모델 사용.
• 로컬 RAG (Chroma) 또는 로컬 MCP 서버 추가.
• 하이브리드 로컬/클라우드 라우팅 전략 설계.

핵심 사고 모델

SLM은 개인 정보 보호, 비용, 오프라인 운영을 위해 범위를 줄입니다. 성공 전략은: SLM이 오케스트레이션하고 도구가 무거운 작업을 맡도록 하는 것. 모델이 코드베이스를 알 필요는 없으며 — 대신 read_file과 search_docs를 언제 호출할지 알아야 합니다. 이는 도구 선택과 같은 제한된 결정에는 SLM이 강하지만, 광범위한 지식이나 긴 다중 단계 추론에는 약한 점을 이용하는 것입니다.

왜 이 특정 구성 요소들인가

• Foundry Local은 OpenAI 호환 HTTP 엔드포인트를 노출하므로 클라우드 에이전트 코드를 base_url만 바꾸고 로컬 플레이스홀더 API 키를 사용해도 이전할 수 있습니다. 또한 머신에 최적화된 빌드(CPU/GPU/NPU)를 자동 선택합니다.
• Qwen 모델은 함수 호출을 위해 훈련되었으며 일관되게 형식에 맞는 도구 호출을 생성합니다 — 로컬 챗 모델을 로컬 에이전트로 만드는 핵심입니다.
• Chroma는 프로세스 내에서 실행되며 벡터를 디스크에 저장하므로 전체 RAG 파이프라인(임베드 → 저장 → 검색 → 추론)이 로컬에 머무릅니다.
• MCP는 클라우드 서비스가 아니라 전송 계층입니다: MCP 서버는 stdio를 통해 로컬에서 실행할 수 있습니다.

설치 필수 요소

foundry model run qwen2.5-7b-instruct
foundry service status

from foundry_local import FoundryLocalManager
from openai import OpenAI

manager = FoundryLocalManager("qwen2.5-7b-instruct")
client = OpenAI(base_url=manager.endpoint, api_key=manager.api_key)  # 로컬 자리 표시자

약 8GB RAM이 현실적인 최소 사양이며 GPU/NPU가 있으면 도움이 되나 필수는 아닙니다.

재현할 주요 패턴

학습자에게 다음 노트북을 안내하세요 17-local-agent-foundry-local.ipynb:

• 샌드박스화된 도구: 모든 파일 도구는 경로를 해석하고 단일 프로젝트 루트 외부는 거부 — 로컬이어도 도구 실행 시 사용자의 권한만 사용합니다.
• 도구 호출 루프: OpenAI 도구 스키마에 도구 등록, 요청된 도구 로컬 실행, 결과 반환, 최종 답변까지 반복.
• 로컬 RAG: 문서를 Chroma 컬렉션에 업서트; search_docs는 상위 k개 청크를 반환.
• 로컬 MCP: stdio로 로컬 서버에 연결; 프로젝트 디렉토리에 범위를 설정하고 출력 유효성 검사.

하이브리드 라우팅 (모델 중 하나로서 로컬)

이는 Lesson 16의 모델 라우팅 아이디어를 반영하며 워크스테이션을 하나의 경로로 활용합니다. 에이전트가 완전히 실패하지 않고 품질이 저하되는 방향으로 로컬 fallback을 선호하세요.

어시스턴트를 위한 가드레일

• 모든 파일/도구 작업을 샌드박스화된 프로젝트 디렉토리 내로 제한하세요.
• 학습자의 명시적 목표가 개인 정보 보호/오프라인일 때는 코드나 데이터를 클라우드로 전송하지 마세요 — 전체 파이프라인을 로컬에 유지하세요.
• SLM 품질에 대해 현실적인 기대를 설정하고, 모델의 암기 지식보다는 도구와 RAG에 의존하세요.
• Lesson 17에는 Foundry Responses 엔드포인트가 없으므로, 클라우드 스모크 테스트 액션은 적용되지 않습니다 — 노트북을 로컬에서 실행해 검증하세요.

면책 조항: 이 문서는 AI 번역 서비스 Co-op Translator를 사용하여 번역되었습니다. 정확성을 기하기 위해 노력하고 있으나, 자동 번역은 오류나 부정확한 부분이 있을 수 있음을 유의하시기 바랍니다. 원본 문서의 원어본이 권위 있는 자료로 간주되어야 합니다. 중요한 정보의 경우, 전문가의 인간 번역을 권장합니다. 이 번역 사용으로 인해 발생하는 오해나 잘못된 해석에 대해 당사는 책임을 지지 않습니다.

Source: microsoft/ai-agents-for-beginners → translations/ko/.agents/skills/local-ai-agents/SKILL.md