AI 에이전트 프레임워크 + MCP 통합 Nanny 레벨 튜토리얼: 외부 도구를 호출할 수 있는 에이전트를 처음부터 구축

🛒 개발자를 위한 환경 준비, MCP 서버 쓰기, LangGraph 공동 디버깅까지 원스톱 입문 튜토리얼입니다.

튜토리얼 목표

이 튜토리얼에서는 외부 도구를 호출할 수 있는 AI 에이전트를 처음부터 구축하는 방법을 안내합니다. 먼저 Python을 사용하여 MCP 표준을 준수하는 도구 서비스(MCP 서버)를 작성한 다음 LangGraph를 사용하여 이를 대화형 에이전트에 연결합니다. 학습 후에는 예제를 실행할 수 있을 뿐만 아니라 자신의 시스템의 API를 도구에 캡슐화하여 에이전트에 연결할 수도 있습니다.

준비 체크리스트

[ ] 인터넷 지원 개발 머신(macOS/Linux/Windows 허용), Python 3.10 이상.
[ ] uv 설치(권장, Python 환경 및 종속성을 관리하는 데 사용됨): curl -LsSf https://astral.sh/uv/install.sh | sh, 그 다음 source ~/.zshrc.
[ ] 사용 가능한 LLM API 키(OpenAI/Anthropic/국내 대형 모델이 허용됩니다. 이 튜토리얼에서는 OpenAI 호환 인터페이스를 예로 사용합니다).
[ ] "실제 도구" 예제 준비: 이 튜토리얼에서는 "로컬 파일 읽기"를 도구로 사용하며 이를 날씨 API 또는 데이터베이스 쿼리로 변경할 수도 있습니다.
[ ] (선택 사항) MCP Inspector 시각적 디버깅 도구를 설치합니다.

버전 팁: MCP SDK와 LangGraph는 빠르게 반복됩니다. 다음 명령의 버전 번호는 공식 실시간 페이지에 따릅니다. 설치에 실패하면 오류 보고서의 프롬프트에 우선순위를 부여하십시오.

1단계: 프로젝트 및 가상 환경 생성

``배쉬 mkdir mcp-agent-demo && cd mcp-agent-demo uv 초기화 --python 3.11 uv "mcp[cli]" 추가 langgraph langchain-openai python-dotenv


참고: `uv init`은 `pyproject.toml` 및 `main.py`를 생성합니다. `mcp[cli]`는 MCP 런타임 및 디버깅 명령을 제공합니다.

## 2단계: 첫 번째 MCP 서버 작성

'로컬 파일 내용 읽기' 도구를 구현하려면 'server.py'를 만듭니다.

``파이썬
mcp.server.fastmcp에서 FastMCP 가져오기

mcp = FastMCP("파일 판독기")

@mcp.tool()
def read_file(경로: str) -> str:
    """지정된 경로에 있는 텍스트 파일의 내용을 읽습니다. 외부 도구를 호출하는 에이전트를 보여주기 위해 사용됩니다."""
    시도해 보세요:
        open(path, "r", 인코딩="utf-8")을 f로 사용:
            f.read(2000)를 반환합니다.
    e와 같은 예외를 제외하고:
        return f"읽기 실패: {e}"

__name__ == "__main__"인 경우:
    mcp.run()

요점: @mcp.tool() 데코레이터는 일반 함수를 도구로 등록하고, 함수 매개변수와 문서 문자열은 모델이 볼 수 있는 도구 스키마를 자동으로 생성합니다. - 모델이 언제 호출해야 하는지 알 수 있도록 설명을 명확하게 작성해야 합니다.

3단계: MCP Inspector로 서버 확인

``배쉬 uv mcp dev server.py 실행


브라우저와 Inspector에서 `http://localhost:6274`를 엽니다.

1. `read_file` 도구를 선택합니다.
2. `{"path": "README.md"}` 매개변수를 입력합니다(먼저 프로젝트에서 README.md를 생성합니다).
3. 통화를 클릭하면 오른쪽에 파일 내용이 반환됩니다.

이 단계에서는 "도구 자체를 사용할 수 있음"을 확인하고 먼저 모델 수준에서 문제를 격리할 수 있습니다.

## 4단계: LangGraph로 에이전트 구축 및 MCP 도구에 연결

`agent.py`를 만듭니다.

``파이썬
비동기 가져오기
langchain_openai에서 ChatOpenAI 가져오기
langgraph.prebuild에서 create_react_agent 가져오기
langchain_mcp_adapters.client에서 MultiServerMCPClient 가져오기

비동기 정의 메인():
    MultiServerMCPClient와 비동기(
        {"file-reader": {"명령": "uv", "args": ["run", "server.py"], "transport": "stdio"}}
    ) 클라이언트로서:
        도구 = client.get_tools()
        모델 = ChatOpenAI(모델="gpt-4o-mini", 온도=0)
        에이전트 = create_react_agent(모델, 도구)
        result = wait Agent.ainvoke({"messages": [("user", "프로젝트의 README.md를 읽고 처음 세 줄을 요약하십시오.")]})
        print(결과["메시지"][-1].content)

__name__ == "__main__"인 경우:
    asyncio.run(메인())

실행:

``배쉬 OPENAI_API_KEY="귀하의 키" 내보내기 uv Python Agent.py 실행


예상 출력: 모델은 먼저 `read_file` 도구를 호출하여 파일을 읽은 다음 반환된 콘텐츠를 기반으로 요약을 제공합니다. 이는 완전한 "에이전트 → MCP → 실제 도구" 링크입니다.

## 5단계: 실제 비즈니스 도구에 연결(예: SQLite 쿼리)

"쿼리 데이터베이스" 도구를 사용하여 `server.py`를 확장합니다.

``파이썬
sqlite3 가져오기

@mcp.tool()
def query_sqlite(db_path: str, sql: str) -> str:
    """SQLite 데이터베이스에 대해 읽기 전용 SELECT 쿼리를 실행하고 결과를 반환합니다."""
    그렇지 않은 경우 sql.strip().lower().startswith("select"):
        "SELECT 쿼리만 허용됩니다"를 반환합니다.
    conn = sqlite3.connect(db_path)
    시도해 보세요:
        행 = conn.execute(sql).fetchmany(10)
        return "\n".join(행의 r에 대해 str(r))
    e와 같은 예외를 제외하고:
        f"쿼리 실패: {e}"를 반환합니다.
    마지막으로:
        연결.닫기()

기업에서 구현하는 경우 이 읽기 전용 쿼리를 "권한 확인을 통한 내부 API 캡슐화"로 바꾸는 것이 프로덕션 수준 도구의 최소 형태입니다.

6단계: 구성, 로그 및 일반적인 오류

로그: ChatOpenAI에 verbose=True를 추가하고 agent.py에 에이전트를 추가하여 각 단계의 도구 호출을 관찰합니다.
시간 초과: 에이전트가 멈추는 것을 방지하기 위해 MCP 도구 호출에 대한 시간 초과를 클라이언트에서 구성할 수 있습니다.
일반적인 오류 보고 및 처리:

오류 현상	가능한 이유	치료
'연결이 거부되었습니다'	서버가 시작되지 않았거나 stdio 경로가 올바르지 않습니다.	`uv run mcp dev server.py`를 사용하여 먼저 확인하세요.
모델이 도구를 호출하지 않습니다	도구 설명이 불분명하거나 모델이 너무 약함	도구 설명을 다시 작성하고 더 강력한 모델로 교체
'도구를 찾을 수 없습니다'	MCP 클라이언트가 도구를 등록하지 못했습니다	`get_tools()` 반환 목록 확인
중국어 왜곡 문자	인코딩 문제	통합 파일 읽기 및 쓰기 `encoding="utf-8"`

확인 방법

도구 계층 확인: MCP Inspector는 각 도구를 개별적으로 테스트합니다.
링크 확인: 에이전트가 3가지 다른 작업을 완료하여 매번 도구가 올바르게 선택되었는지 확인하도록 합니다.
회귀 검증: 사용 사례를 스크립트로 통합하고 수정 후 다시 실행합니다.

자주 묻는 질문(FAQ)

MCP는 Python을 사용해야 합니까?

아니요. 공식 SDK는 Python과 TypeScript를 지원하며, Node 환경은 @modelcontextprotocol/sdk를 사용합니다.
로컬 GPU가 없어도 이 튜토리얼을 사용할 수 있나요?

할 수 있는. 이 튜토리얼의 LLM은 API를 사용하고 대규모 모델 추론에만 컴퓨팅 성능이 필요하며 가벼운 도구 서비스만 로컬에서 실행됩니다.
상담원이 도구를 호출하지 않으면 어떻게 해야 합니까?

먼저 도구 설명에 "호출 시기"라는 트리거 조건이 포함되어 있는지 확인하고, 두 번째로 모델에 함수 호출 기능이 있는지 확인한 다음, 마지막으로 더 간단한 프롬프트를 사용하여 테스트합니다.

프로덕션 환경에 MCP 서버를 배포하는 방법은 무엇입니까?

서버는 stdio 대신 스트리밍 가능한 HTTP 전송을 사용하고 통합 인증에 액세스하여 독립적인 프로세스/컨테이너로 배포될 수 있습니다.
여러 도구가 서로 간섭합니까?

각 도구에는 독립적인 네임스페이스와 스키마가 있습니다. 설명이 명확하고 권한이 최소화되면 일반적으로 간섭이 발생하지 않습니다. 동시성이 높은 시나리오에서는 흐름을 제한하는 것이 좋습니다.

고도화 및 확장

다중 에이전트 오케스트레이션: LangGraph의 상태 시스템을 사용하여 "계획-실행-검토"를 여러 역할로 분할합니다.
MCP 레지스트리: 버전과 권한을 통합하기 위해 내부 도구 등록 센터를 구축합니다.
평가 세트: 행동 표류를 방지하기 위해 비즈니스 사용 사례를 자동화된 회귀로 촉진합니다.
민영화: LLM을 로컬 배포 모델(예: Ollama)로 대체하여 전체 링크 인트라넷 운영을 달성합니다.

사용자 후기

후기를 불러오는 중...