Skip to main content
create_agent를 실무에서 쓰려면 아래 요소를 먼저 설계합니다.

​
1) 모델 선택

  • Tool calling 지원 여부를 확인합니다.
  • 비용/속도/정확도 트레이드오프를 먼저 정합니다.
agent = create_agent(
    model="openai:gpt-4.1-mini",
    tools=[...],
)

​
2) 도구 설계

도구는 에이전트의 행동 공간입니다. docstring과 타입 힌트를 명확하게 작성합니다. 
from langchain.tools import tool

@tool
def search_docs(query: str) -> str:
    """내부 문서에서 질의를 검색합니다."""
    ...

​
3) 시스템 프롬프트

시스템 프롬프트에는 정책과 우선순위를 넣으세요.
  • 언제 어떤 도구를 쓸지
  • 어떤 기준으로 답변을 멈출지
  • 금지 동작(보안/정책)

​
4) 메모리와 상태

create_agent는 messages 상태를 기반으로 동작합니다. 대화 스레드 분리를 위해 thread_id를 사용합니다. 
config = {"configurable": {"thread_id": "user-42"}}
agent.invoke(
    {"messages": [{"role": "user", "content": "내 선호를 기억해줘"}]},
    config=config,
)

​
단기/장기 메모리 관점

  • 단기 메모리: 현재 thread의 messages
  • 장기 메모리: LangGraph store 연동이 필요 (고급)

​
5) 미들웨어

미들웨어로 안전성과 운영성을 높이세요.
  • Human-in-the-loop 승인
  • 모델 fallback/라우팅
  • 정책 검사/가드레일

​
5-1) HITL 기본 정책

입문자라면 먼저 아래 2가지만 적용합니다.
  • 외부 쓰기 도구(메일/DB)에만 승인 요구
  • approve / reject / edit-args 3가지 decision만 사용

​
6) 구조화된 출력

후속 시스템이 파싱해야 하는 경우 구조화된 출력이 필요합니다. 
from pydantic import BaseModel

class Answer(BaseModel):
    summary: str
    confidence: float

agent = create_agent(
    model="openai:gpt-4.1-mini",
    tools=[...],
    response_format=Answer,
)

​
추천 학습 순서

  1. create_agent 최소 예제
  2. 도구 2~3개로 Tool-calling
  3. 구조화된 출력 + 오류 처리
  4. LangGraph로 라우팅/병렬화 확장
  5. create_deep_agent로 장시간 자율 실행 확장

다음: LangGraph 기초

상태 기반 오케스트레이션으로 에이전트 제어력을 높입니다.

​
실무 적용 체크리스트

  • 목표와 성공 기준을 먼저 정의했습니다.
  • 예제를 현재 프로젝트 컨텍스트로 치환했습니다.
  • 실패 시 복구 절차를 문서화했습니다.
  • 다음 단계 문서로 연결해 학습 흐름을 유지합니다.

​
자주 나는 실수

  1. 학습 목표 없이 예제를 복사해 적용해 실패합니다.
  2. 성공/실패 기준이 없어 품질을 판단하지 못합니다.
  3. 다음 단계 연결 없이 문서를 단절적으로 소비합니다.

​
다음 문서

다음: LangGraph 기초

학습 흐름을 이어서 진행합니다.