Deep Agents 0.7.22: 스킬을 읽은 뒤 필요한 도구만 여는 방법

Deep Agents 0.7.22에서는 필요한 스킬을 읽은 뒤 해당 업무의 도구만 모델에 공개할 수 있다. 도구를 SkillsMiddleware(tools=...)에 등록하고 스킬의 metadata.include_tools와 연결하는 방식이다. 여러 업무를 처리하는 에이전트라면 조회 도구 하나부터 옮겨 호출 경로를 확인해 볼 만하다. 공식 0.7.22 릴리스

고객 문의를 분류하고, 이슈를 찾고, 릴리스 내용을 정리하는 에이전트를 한 프로세스에 넣다 보면 도구 목록이 빠르게 길어진다. 실제 요청은 한 가지인데 모델에는 여러 업무의 함수 설명과 인자 스키마가 함께 전달된다. 이때 먼저 검토할 개선은 업무 지침과 도구를 같은 단위로 묶고, 필요한 시점에만 도구를 공개하는 구조다.

이 기능은 2026년 10월 5일 배포됐으며, 이 글은 10월 6일 확인한 해당 버전을 기준으로 한다. 기존 에이전트의 도구 등록 방식을 작게 바꾸고 싶은 1인 개발자와 소규모 팀을 위한 적용 가이드다.

먼저 확인할 패키지와 적용 범위

대상은 LangChain의 Python 패키지 deepagents이며 공식 저장소는 langchain-ai/deepagents다. 확인 시점 PyPI 최신 배포는 0.7.22, 등록된 maintainer는 langchain, 라이선스는 MIT다. Python 요구 범위는 >=3.11,<4.0이고 개발 상태 classifier는 Beta다. 버전 번호에 사전 배포 접미사가 없다는 사실과 프로젝트의 Beta 표기는 구분해서 읽어야 한다. CLI 패키지나 JavaScript SDK에 같은 API가 있다고 가정하지 않는다. PyPI 버전 정보

유지보수 상태는 실제 변경으로 확인할 수 있다. 이번 기능의 PR #6552는 10월 2일 병합됐고 10월 5일 릴리스에 포함됐다. 릴리스에는 텍스트 덮어쓰기 시 이전 인코딩 상태를 초기화하는 수정도 있다. 이 기록은 최근 변경이 배포됐다는 근거이며, 장기 지원이나 장애 대응 시간을 보장하지 않는다. 기능 PR, 릴리스 기록

기존 서비스에서는 의존성도 함께 살핀다. 0.7.22 태그의 선언은 langchain>=1.4.3,<2.0.0, langchain-core>=1.6.6,<2.0.0 등을 요구한다. 오래된 LangChain 환경에서 패키지 하나만 교체하는 변경으로 취급하기 어렵다. 먼저 별도 브랜치에서 전체 의존성 변경 범위를 검토하는 편이 좋다. 태그에 고정된 의존성 선언

스킬을 읽는 순간이 도구 공개 시점이 된다

스킬은 업무 설명과 절차를 담은 SKILL.md를 중심으로 구성된다. 시작할 때는 스킬의 이름과 설명으로 필요한 업무를 고르고, 해당 파일을 읽어 구체적인 절차를 얻는다. 새 기능에서는 frontmatter의 metadata.include_tools에 도구 이름을 적는다. 값은 공백으로 구분한 문자열이며 YAML 목록으로 작성하면 의도한 이름에 매칭되지 않는다. 이 필드는 Deep Agents의 확장이므로 다른 Agent Skills 구현으로 옮길 때는 별도 확인이 필요하다. 공식 스킬 도구 가이드

도구 객체를 전달하는 위치가 핵심이다. 지연 공개할 도구는 create_deep_agent(tools=...) 대신 SkillsMiddleware(tools=...)에 넣는다. 이 경로의 도구는 모델이 관련 스킬을 read_file로 읽기 전에는 호출할 수 없다. 대화 요약으로 해당 읽기 기록이 문맥에서 사라지면 다시 스킬을 읽어야 한다. 따라서 활성 상태를 영구적인 사용자 권한처럼 저장하거나 해석하면 안 된다. 0.7.22 SkillsMiddleware 소스

최소 예제는 조회 도구 하나로 시작한다

가상의 서비스 오류 안내 도구를 만든다고 하자. 예제의 데이터는 코드 안에 있는 샘플 문자열이며 실제 고객 정보나 외부 API를 사용하지 않는다. 프로젝트 아래 agent_workspace/skills/incident-lookup/SKILL.md를 만들고 다음 내용을 저장한다. 스킬의 설명에는 어떤 질문에서 사용할지 넣고, 본문에는 결과에 없는 내용을 추측하지 않도록 작업 절차를 적는다.

---
name: incident-lookup
description: 서비스의 알려진 장애를 조회한다. 로그인 또는 결제 오류 질문에 사용한다.
metadata:
  include_tools: lookup_incident
---

# 장애 안내
1. 사용자가 말한 서비스가 login인지 checkout인지 확인한다.
2. lookup_incident를 호출한다.
3. 조회 결과와 확인되지 않은 내용을 구분해서 답한다.
4. 서비스가 불분명하면 먼저 질문한다.

아래 Python 코드는 공식 문서의 연결 방식을 이 사례에 맞게 구성한 예다. AGENT_MODEL에는 도구 호출을 지원하는 LangChain 모델 식별자를 지정하고, 해당 공급자의 연동 패키지와 인증 설정을 별도로 준비해야 한다. 실행하면 모델 API 호출과 비용이 발생할 수 있다. 이 글 작성 과정에서는 패키지를 설치하거나 코드를 실행하지 않았다.

import os

from deepagents import FilesystemPermission, create_deep_agent
from deepagents.backends.filesystem import FilesystemBackend
from deepagents.middleware import SkillsMiddleware
from langchain.tools import tool


@tool
def lookup_incident(service: str) -> str:
    """샘플 데이터에서 login 또는 checkout의 알려진 장애를 조회한다."""
    incidents = {
        "login": "샘플: 로그인 응답 지연을 조사 중입니다.",
        "checkout": "샘플: 등록된 결제 장애가 없습니다.",
    }
    return incidents.get(service, "알 수 없는 서비스입니다.")


backend = FilesystemBackend(
    root_dir="./agent_workspace",
    virtual_mode=True,
)

agent = create_deep_agent(
    model=os.environ["AGENT_MODEL"],
    backend=backend,
    permissions=[
        FilesystemPermission(
            operations=["write"], paths=["/**"], mode="deny"
        ),
    ],
    middleware=[
        SkillsMiddleware(
            backend=backend,
            sources=["/skills/"],
            tools=[lookup_incident],
        ),
    ],
)

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "login 서비스의 알려진 장애를 확인해 주세요.",
    }]
})
print(result["messages"][-1].content)

sources는 개별 스킬 폴더가 아닌 그 상위 /skills/를 가리킨다. virtual_mode=True에서 이 경로는 지정한 backend 루트 안의 경로다. skills=를 추가로 넘기는 대신 직접 만든 미들웨어에 소스와 도구를 함께 전달했다. 예제의 쓰기 금지 규칙은 내장 파일 도구에 적용되며, 사용자 정의 함수의 동작을 자동으로 제한하지 않는다. 스킬 연결 예제, 파일 권한의 적용 범위

도구가 안 보이면 등록 위치부터 확인한다

다음 순서로 확인하면 모델을 바꾸거나 프롬프트를 길게 덧붙이기 전에 설정 오류를 좁힐 수 있다. 첫 번째 실행에서는 의도적으로 업무를 명확히 적고, 정상 경로를 확인한 뒤 모호한 질문을 추가하는 편이 진단하기 쉽다.

  • 시작부터 도구가 보인다: 같은 함수를 에이전트의 최상위 tools에도 넣었는지 확인한다. 이미 공개된 도구는 include_tools로 숨겨지지 않는다.
  • 스킬 자체를 고르지 않는다: 폴더 깊이, SKILL.md 이름, frontmatter의 name과 description을 점검한다. 설명이 실제 사용자 질문과 연결되는지도 확인한다.
  • 읽었는데 도구가 없다: include_tools의 철자와 문자열 형식, 실제 도구 이름을 대조한다. 함수 이름을 바꿨다면 스킬도 함께 수정한다.
  • 긴 대화에서 다시 사라진다: 요약 이후 스킬 읽기 기록이 남아 있는지 확인하고 필요한 스킬을 다시 읽게 한다.

이 동작들은 태그 소스의 스킬 메타데이터 처리와 도구 활성 조건을 기준으로 정리했다. 공급자의 도구 검색에 등록한 deferred tool은 검색으로 먼저 찾을 수도 있다. 스킬을 반드시 읽어야 하는 경로가 필요하다면 두 등록 방식을 섞기 전에 이 차이를 확인해야 한다.

권한 검사는 도구 실행 경로에 남겨 둔다

이 기능으로 설계할 수 있는 것은 업무별 도구 공개 순서다. 실제 서비스에서는 계정의 조회 범위, 테넌트 경계, 쓰기 승인, 호출 횟수 제한을 별도로 검사해야 한다. 예를 들어 사용자가 스킬 파일을 읽었다고 해서 다른 조직의 장애 기록을 조회할 권한이 생기지는 않는다. 도구 구현이나 서버가 인증된 실행 문맥을 기준으로 허용 범위를 판단하도록 구성한다.

내장 파일 권한도 적용 범위를 정확히 알아야 한다. 공식 문서는 이 규칙이 사용자 정의 파일 접근 도구나 MCP 도구에는 적용되지 않으며, 임의 명령 실행이 가능한 sandbox backend에도 그대로 적용되지 않는다고 설명한다. 샘플의 쓰기 금지 한 줄을 전체 프로세스의 보안 격리로 설명해서는 안 된다. 공식 권한 문서

작은 팀이라면 스킬 작성 권한과 도구 배포 권한도 구분해 두자. 고객이 올린 파일을 그대로 업무 스킬로 채택하는 대신, 팀이 검토한 디렉터리만 소스로 연결한다. 외부 문서에 적힌 도구 이름이나 지시문은 실제 권한 결정의 근거가 될 수 없다. 스킬 변경은 코드 리뷰에 함께 올려 어떤 업무에서 어떤 함수가 열리는지 사람이 확인할 수 있게 한다.

도입 판단은 작은 비교 실험으로 한다

이 구조는 서로 다른 업무가 여러 도구를 공유하는 에이전트에 검토할 가치가 있다. 반대로 매번 같은 조회 함수 두 개만 사용하는 봇이라면 스킬 선택과 파일 읽기가 추가 관리 지점이 될 수 있다. 먼저 가장 분명하게 구분되는 업무 하나만 옮기고 나머지 도구 등록은 유지하는 점진적 변경을 권한다.

비교 입력은 정상 질문, 정보가 부족한 질문, 범위 밖 질문으로 나눈다. 장애 조회 예제라면 로그인 장애 질문, 서비스 이름이 빠진 오류 질문, 결제 환불 요청을 준비할 수 있다. 각 입력에서 어떤 스킬을 읽었는지, 도구를 어떤 인자로 호출했는지, 답변에 확인되지 않은 내용을 더했는지 기록한다. 답변 문장만 보고 성공을 판단하면 잘못된 도구 경로가 가려질 수 있다.

그다음 실제 서비스에서 중요한 수치를 정한다. 최초 응답 시간, 모델 요청 수, 입력 토큰, 잘못 선택한 도구 수를 같은 모델과 비슷한 입력으로 비교하면 된다. 도구 스키마를 나중에 넣더라도 스킬을 읽는 단계가 추가되므로 지연 시간이 반드시 줄어들지는 않는다. 프롬프트 캐시 영향도 모델의 중간 도구 추가 지원 여부에 따라 달라진다. 절감률은 직접 측정하기 전까지 적지 않는 편이 정확하다. 공식 문서의 캐시 관련 설명

롤백 기준도 미리 정해 두면 운영 부담이 줄어든다. 업무 스킬을 선택하지 못하는 비율이 늘거나 추가 왕복 때문에 응답 목표를 넘긴다면 해당 업무만 기존 등록 방식으로 되돌린다. 스킬 파일과 등록 코드, 비교 입력을 한 변경 단위로 관리하면 원인을 찾기 쉽다. 처음부터 모든 업무를 옮길 필요는 없다.

핵심은 필요한 도구를 언제 보여 줄지 코드와 스킬이 함께 결정하도록 만드는 것이다. 0.7.22는 그 연결 지점을 제공한다. 도구 하나와 명확한 업무 하나로 시작해 호출 경로를 확인하고, 실제 품질과 비용을 측정한 뒤 확대하면 작은 팀도 관리 가능한 범위에서 적용할 수 있다.

작성 기준: 2026년 10월 6일, Deep Agents 0.7.22. AI의 도움으로 공식 릴리스, 문서, 태그 소스를 대조해 작성했다. 예제는 설명용으로 구성했으며 패키지 설치, 모델 호출, 실행 검증은 수행하지 않았다. 운영 도입 전에는 선택한 모델과 의존성 조합에서 동작을 검증해야 한다.

댓글

댓글 쓰기