Deep Agents

Deep Agents

복잡한 작업을 처리하는 에이전트를 만들 때 Deep Agents를 쓰고 있다면, 그 실행도 추적하고 싶죠. Deep Agents는 파일 시스템 도구와 서브에이전트 위임이 내장된 LangChain의 에이전트 프레임워크예요. confident-trace로 init()을 한 번 호출하면, 에이전트 실행·모델 호출·도구를 Observatory에서 자동으로 확인할 수 있습니다.

출처: 문서

본문

개요

Deep Agents는 복잡한 작업을 위한 LangChain의 에이전트 프레임워크로, 파일 시스템 도구와 서브에이전트 위임이 내장되어 있어요. Confident AI는 confident-trace로 Deep Agents 애플리케이션을 자동 추적합니다 — init()을 한 번 호출하면 에이전트 실행, 모델 호출, 도구를 Observatory에서 볼 수 있죠.

이 통합은 Deep Agents 애플리케이션에서 다음 스팬을 포착합니다.

  • 에이전트 실행 — 그래프 호출, 노드, 중간 runnable과 그 부모-자식 관계
  • 서브에이전트 위임 — task 도구 호출과 중첩된 서브에이전트의 모델·도구 실행
  • LLM 스팬 — 모델 상세, 토큰 사용량, 완료 사유, 요청된 도구 호출을 포함한 입출력 메시지
  • 도구 스팬 — 내장 파일 시스템 도구와 커스텀 도구, 입력 매개변수와 출력 포함

Deep Agents는 LangChain과 LangGraph와 같은 콜백 브리지를 사용합니다. 콜백 핸들러를 전달하거나 각 서브에이전트를 따로 계측할 필요가 없어요. 프레임워크 스팬은 LangGraph 통합 라벨을 유지합니다.

Runtime Requirements Setup
Python Python 3.11+, deepagents 0.7.x and your model integration Call init() before invoking your agent
TypeScript Not validated by this integration —

자동 계측

의존성 설치

confident-trace를 Deep Agents 및 에이전트가 쓰는 모델 통합과 함께 설치하세요. 이 예제는 OpenAI를 사용합니다.

pip install confident-trace 'deepagents>=0.7.13,<0.8' 'langchain-openai>=1,<2'

API 키 설정

Confident AI Project API key를 받아 모델 프로바이더 키와 함께 환경 변수로 설정하세요.

export CONFIDENT_API_KEY="<your-confident-project-key>"
export OPENAI_API_KEY="<your-openai-key>"

EU 리전이거나 자체 호스팅 배포라면 CONFIDENT_OTEL_ENDPOINT도 설정하세요 — init() 구성을 참고하세요.

Deep Agents 계측

에이전트를 실행하기 전에 init()을 한 번 호출하세요. 설치된 LangChain·LangGraph 패키지를 감지해 공유 추적 브리지를 자동으로 붙여 줘요.

from confident_trace import init, shutdown
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI

init()

def get_weather(city: str) -> str:
    """Return example weather for a city."""
    return f"It's sunny in {city}."

agent = create_deep_agent(
    name="weather-assistant",
    model=ChatOpenAI(model="gpt-4.1-mini"),
    tools=[get_weather],
    system_prompt="Use get_weather to answer weather questions.",
)

try:
    result = agent.invoke(
        {"messages": [{"role": "user", "content": "What is the weather in San Francisco?"}]}
    )
    print(result["messages"][-1].content)
finally:
    shutdown()

장기 실행 서버에서는 시작 시 init()을 한 번, 정상 종료 시 활성 에이전트 실행이 끝난 뒤 shutdown()을 한 번 호출하세요 — 요청마다 하지 마세요. 한 번 초기화를 참고하세요.

Deep Agents 실행

스크립트를 실행해 트레이스를 Confident AI로 보내세요.

python main.py

완료 ✅. Confident AI 프로젝트에서 Observatory를 열어 트레이스와 그래프·모델·도구 스팬을 확인하세요.

트레이스가 안 보이면, 프로그램이 종료되기 전에 shutdown()을 호출하거나, 장기 실행 프로세스에서 보류 중인 스팬을 내보내야 할 때 flush()를 호출하세요. 트러블슈팅을 참고하세요.

서브에이전트 추적

Deep Agents는 task 도구를 통해 작업을 위임합니다. 추적 브리지는 그 위임을 자동으로 따라가요 — 병렬 서브에이전트와 각각 안의 모델·도구 호출까지 포함해서요.

빠른 시작에 서브에이전트를 추가하려면, agent = create_deep_agent(...) 블록을 다음으로 교체하세요. 기존 init(), 호출, 종료 코드는 그대로 두세요.

model = ChatOpenAI(model="gpt-4.1-mini")

agent = create_deep_agent(
    name="weather-coordinator",
    model=model,
    system_prompt="Delegate weather questions to weather-researcher, then summarize its answer.",
    subagents=[
        {
            "name": "weather-researcher",
            "description": "Look up weather for the requested city.",
            "system_prompt": "Use get_weather to answer the question.",
            "model": model,
            "tools": [get_weather],
        }
    ],
)

코디네이터가 위임하면, 그 트레이스에는 task 도구 스팬, 중첩된 weather-researcher 그래프, 그리고 그 서브에이전트의 모델·get_weather 도구 스팬이 포함돼요. 정확한 노드와 모델 호출 수는 에이전트의 실행에 달려 있습니다.

무엇이 포착되나

  • 그래프·노드 — LangGraph 콜백이 보고하는 각 에이전트 호출, 중첩된 서브에이전트 그래프, 노드, 중간 runnable
  • 모델 호출 — 이용 가능한 모델 정보, 토큰 사용량, 완료 사유, 정규화된 메시지를 담은 LLM 스팬
  • 도구 실행 — 위임, write_file 같은 파일 시스템 작업, 그리고 자체 도구에 대한 도구 스팬
  • 플래닝 도구 — 에이전트에 TodoListMiddleware가 활성화되어 있을 때의 write_todos 호출
  • 커스텀 스팬 — 노드나 도구 안에서 만든 애플리케이션 스팬이 그 실행의 OpenTelemetry 컨텍스트를 상속

입력, 출력, 메시지는 콘텐츠 정책을 따릅니다. 이 트레이스는 SDK 실행을 포착해요. 별도 샌드박스 프로세스에서 실행되는 명령은 내부 스팬을 위해 자체 계측이 필요합니다.

그래프와 노드는 프레임워크가 명시적으로 에이전트로 식별하지 않는 한 일반 스팬이에요. 에이전트 이름만으로 스팬 유형이 바뀌지 않습니다. 명시적으로 타입이 지정된 에이전트 스팬이 필요하면 호출을 span(type="agent")으로 감싸세요.

스트리밍과 비동기 실행

같은 설정이 invoke, ainvoke, stream, astream을 추적합니다. 예를 들어, 빠른 시작의 try 블록 안 호출을 스트리밍 호출로 바꿔 보세요.

for state in agent.stream(
    {"messages": [{"role": "user", "content": "What is the weather in San Francisco?"}]},
    stream_mode="values",
):
    print(state["messages"][-1].content)

shutdown()을 호출하기 전에 스트림을 끝까지 소비하거나, 일찍 멈출 땐 닫아 주세요. flush와 shutdown을 참고하세요.

트레이스 스팬 속성 설정

호출이 시작되기 전에 아는 속성을 추가하려면 트레이스 컨텍스트를 사용하세요. 추가 스팬은 만들지 않아요. agent.invoke()가 시작한 트레이스가 태그, 메타데이터, 사용자 ID, 고객 ID를 상속받습니다.

from confident_trace import trace_context

with trace_context(
    tags=["weather"],
    metadata={"release": "2026-09"},
    user_id="user-42",
    customer_id="customer-7",
):
    result = agent.invoke(
        {"messages": [{"role": "user", "content": "What is the weather in San Francisco?"}]}
    )

초기화된 애플리케이션에서 shutdown 전에 사용하세요. 각 ID와 함께 선택적 표시 이름을 설정하려면 사용자와 고객을, 지원되는 모든 속성은 트레이스 컨텍스트를 참고하세요.

다중 턴 계측

에이전트를 체크포인터로 만들고, 호출 간에 configurable.thread_id를 재사용해 대화 상태를 유지하세요. Python 통합은 이 스레드 ID를 읽고 각 호출의 트레이스를 같은 대화에 연결합니다.

from langgraph.checkpoint.memory import InMemorySaver

agent = create_deep_agent(
    model=ChatOpenAI(model="gpt-4.1-mini"),
    tools=[get_weather],
    system_prompt="Use get_weather to answer weather questions.",
    checkpointer=InMemorySaver(),
)

config = {"configurable": {"thread_id": "weather-chat-42"}}
for prompt in ["What is the weather in San Francisco?", "And in New York?"]:
    result = agent.invoke(
        {"messages": [{"role": "user", "content": prompt}]},
        config,
    )
    print(result["messages"][-1].content)

이 에이전트 구성과 호출 루프를 해당하는 빠른 시작 코드 대신 사용하고, 초기화와 종료는 유지하세요. InMemorySaver는 현재 프로세스 동안 상태를 유지합니다. 재시작에도 상태가 남아야 한다면 영속 체크포인터를 사용하세요.

사람 확인 인터럽트는 정상적인 제어 흐름입니다. Command(resume=...)로 재개하면 새 호출 트레이스가 만들어지고 대화 ID는 유지돼요. LangGraph 체크포인트·재개 동작과 스레드를 참고하세요.

Deep Agents 계측 비활성화

특정 통합만 활성화하려면 init()에 통합 식별자 목록을 전달하세요. "deepagents", "langgraph", "langchain" 모두 같은 콜백 브리지를 활성화하므로, 프레임워크 추적을 끄려면 셋 다 빼야 해요. 빈 튜플은 모든 자동 계측을 비활성화합니다.

from confident_trace import init

init(instrumentations=())
# Use ("deepagents",) to enable only the shared framework bridge.

모델 프로바이더 통합을 켜 둔 채로 두면, 프레임워크 브리지와 무관하게 직접 프로바이더 호출을 계속 포착할 수 있어요.

다음 단계

에이전트를 추적했으니, 더 깊이 들어가 볼까요.

Online Evals

트레이스·스팬이 Confident AI로 수집되는 실시간으로 평가를 돌려 에이전트 품질을 모니터링하세요.

Threads

같은 대화의 에이전트 실행을 스레드로 묶고, 전체 대화를 하나의 단위로 평가하세요.

더 알아보기

  • LangGraph — 그래프·노드·체크포인트 대화 추적
  • LangChain — 체인과 runnable 추적
  • Online Evals — 실시간 트레이스·스팬 평가