Skip to main content

agent-dev

Tool Calling, 상태 관리, API 서빙을 포함한 AI Agent 개발 환경입니다.

문서 기준

  • 기준일: 2026-02-23
  • Python: 3.12
  • 운영체제: macOS, Ubuntu, Windows
  • 동기화 명령: uv sync

호환성 메모

환경지원 수준설명
macOS / Ubuntu / Windows전체 동기화모든 패키지 OS 무관 설치 가능
이 환경은 PyTorch를 포함하지 않습니다. LLM 추론은 OpenAI API 등 외부 서비스를 통해 수행하며, 로컬 모델이 필요하면 vllm-serving 환경과 조합하세요.

Agent 개발에서 패키지 역할

패키지역할비고
langchain체인/프롬프트 오케스트레이션Tool, Memory, Chain 구성
langgraph상태 기반 Agent 그래프노드/엣지로 Agent 워크플로우 정의
langsmithAgent 실행 추적 및 디버깅트레이스 시각화, 평가 데이터셋
pydantic데이터 검증 및 스키마 정의Tool 입출력, API 모델 정의
fastapi / uvicornAgent API 서빙REST API 엔드포인트 제공
httpx비동기 HTTP 클라이언트외부 API, MCP 서버 호출
openaiLLM 호출 클라이언트GPT 시리즈 모델 연동
tiktoken토큰 카운팅프롬프트 길이 관리, 비용 추정

pyproject.toml

[project]
name = "agent-dev"
version = "0.1.0"
description = "AI agent development environment"
requires-python = "==3.12.*"
dependencies = [
  "langchain==1.2.10",
  "langgraph==1.0.9",
  "langsmith==0.7.6",
  "pydantic==2.12.5",
  "fastapi==0.130.0",
  "uvicorn==0.41.0",
  "httpx==0.28.1",
  "openai==2.21.0",
  "tiktoken==0.12.0",
  "ipykernel==7.2.0",
  "pytest==9.0.2",
  "ruff==0.15.2",
]

[tool.uv]
package = false

설치

1

프로젝트 생성

uv init agent-dev
cd agent-dev
2

의존성 락 및 동기화

uv lock
uv sync
3

Jupyter 커널 등록

uv run python -m ipykernel install --user --name agent-dev --display-name "UV agent-dev"

설치 확인

uv run python -c "import langchain, langgraph, langsmith, fastapi, httpx, openai; print('langgraph', langgraph.__version__); print('fastapi', fastapi.__version__); print('openai', openai.__version__)"

기본 사용 예시

LangGraph를 이용한 Tool Calling Agent 기본 구조입니다.
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent

# 1) Tool 정의
@tool
def get_weather(city: str) -> str:
    """도시의 현재 날씨를 반환합니다."""
    return f"{city}의 현재 날씨: 맑음, 22도"

@tool
def search_docs(query: str) -> str:
    """내부 문서를 검색합니다."""
    return f"'{query}'에 대한 검색 결과: 관련 문서 3건 발견"

# 2) Agent 생성
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
agent = create_react_agent(llm, tools=[get_weather, search_docs])

# 3) Agent 실행
result = agent.invoke({"messages": [("user", "서울 날씨 알려줘")]})
print(result["messages"][-1].content)

MCP 서버 연동 참고

Agent에서 외부 MCP 서버를 호출할 때는 httpx를 사용합니다.
import httpx

async def call_mcp_tool(server_url: str, tool_name: str, arguments: dict):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{server_url}/tools/{tool_name}",
            json={"arguments": arguments},
            timeout=30.0
        )
        return response.json()
LangSmith 추적을 활성화하려면 환경변수 LANGCHAIN_TRACING_V2=trueLANGCHAIN_API_KEY를 설정하세요. 트레이스는 smith.langchain.com에서 확인할 수 있습니다.

트러블슈팅

증상원인해결
LangSmith 추적 미기록LANGCHAIN_API_KEY 또는 LANGCHAIN_TRACING_V2 미설정환경변수 확인 및 true 설정
비동기 이벤트 루프 충돌Jupyter 내에서 asyncio.run() 중복 호출nest_asyncio 설치 또는 await 직접 사용
uv sync 의존성 충돌기존 락 파일과 버전 불일치uv lock --refreshuv sync
Tool 호출 결과 누락Tool 함수 반환 타입이 str이 아님반환값을 문자열로 변환 확인
FastAPI 서버 시작 실패포트 충돌lsof -i :8000으로 점유 프로세스 확인
OpenAI API 타임아웃네트워크 지연 또는 모델 과부하timeout 파라미터 증가, 재시도 로직 추가