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 워크플로우 정의 |
langsmith | Agent 실행 추적 및 디버깅 | 트레이스 시각화, 평가 데이터셋 |
pydantic | 데이터 검증 및 스키마 정의 | Tool 입출력, API 모델 정의 |
fastapi / uvicorn | Agent API 서빙 | REST API 엔드포인트 제공 |
httpx | 비동기 HTTP 클라이언트 | 외부 API, MCP 서버 호출 |
openai | LLM 호출 클라이언트 | 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
프로젝트 생성
uv init agent-dev
cd agent-dev
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=true와 LANGCHAIN_API_KEY를 설정하세요. 트레이스는 smith.langchain.com에서 확인할 수 있습니다.
트러블슈팅
| 증상 | 원인 | 해결 |
|---|
| LangSmith 추적 미기록 | LANGCHAIN_API_KEY 또는 LANGCHAIN_TRACING_V2 미설정 | 환경변수 확인 및 true 설정 |
| 비동기 이벤트 루프 충돌 | Jupyter 내에서 asyncio.run() 중복 호출 | nest_asyncio 설치 또는 await 직접 사용 |
uv sync 의존성 충돌 | 기존 락 파일과 버전 불일치 | uv lock --refresh 후 uv sync |
| Tool 호출 결과 누락 | Tool 함수 반환 타입이 str이 아님 | 반환값을 문자열로 변환 확인 |
| FastAPI 서버 시작 실패 | 포트 충돌 | lsof -i :8000으로 점유 프로세스 확인 |
| OpenAI API 타임아웃 | 네트워크 지연 또는 모델 과부하 | timeout 파라미터 증가, 재시도 로직 추가 |