> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baeum.ai.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# agent-dev

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

## 문서 기준

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

## 호환성 메모

| 환경                       | 지원 수준  | 설명                 |
| ------------------------ | ------ | ------------------ |
| macOS / Ubuntu / Windows | 전체 동기화 | 모든 패키지 OS 무관 설치 가능 |

<Note>
  이 환경은 PyTorch를 포함하지 않습니다. LLM 추론은 OpenAI API 등 외부 서비스를 통해 수행하며, 로컬 모델이 필요하면 `vllm-serving` 환경과 조합합니다.
</Note>

## 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

```toml theme={null}
[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
```

## 설치

<Steps>
  <Step title="프로젝트 생성">
    ```bash theme={null}
    uv init agent-dev
    cd agent-dev
    ```
  </Step>

  <Step title="의존성 락 및 동기화">
    ```bash theme={null}
    uv lock
    uv sync
    ```
  </Step>

  <Step title="Jupyter 커널 등록">
    ```bash theme={null}
    uv run python -m ipykernel install --user --name agent-dev --display-name "UV agent-dev"
    ```
  </Step>
</Steps>

## 설치 확인

```bash theme={null}
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 기본 구조입니다.

```python theme={null}
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`를 사용합니다.

```python theme={null}
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()
```

<Tip>
  LangSmith 추적을 활성화하려면 환경변수 `LANGCHAIN_TRACING_V2=true`와 `LANGCHAIN_API_KEY`를 설정합니다. 트레이스는 [smith.langchain.com](https://smith.langchain.com)에서 확인할 수 있습니다.
</Tip>

## 트러블슈팅

| 증상               | 원인                                                | 해결                                 |
| ---------------- | ------------------------------------------------- | ---------------------------------- |
| 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` 파라미터 증가, 재시도 로직 추가       |

## 설치 점검 목록

* 관리자 권한/필수 도구 등 사전 요구사항을 먼저 확인했습니다.
* 설치 후 버전 확인 명령어(`--version`)를 실행해 정상 설치를 검증했습니다.
* PATH/환경변수 변경이 필요한 경우 터미널을 다시 열어 적용 여부를 확인했습니다.
* 문제가 생겼을 때를 대비해 설치 로그 또는 스크린샷을 남겼습니다.

## 관련 문서

<CardGroup cols={2}>
  <Card title="Setup 홈" icon="house" href="/setup/index">
    운영체제별 설치 흐름을 다시 확인합니다.
  </Card>

  <Card title="다음: llm-finetune" icon="arrow-right" href="/setup/uv-env/llm-finetune">
    다음 설치 단계를 이어서 진행합니다.
  </Card>
</CardGroup>