Deep Agents 도구

Deep Agents 도구 (Tools)

Deep Agents는 여러분이 정의하는 도구, 어떤 LangChain 도구든, 그리고 어떤 MCP 서버의 도구든 모두 호출할 수 있어요. 이 도구들을 create_deep_agent의 tools= 파라미터로 넘기면, 파일 관리와 서브에이전트 생성을 위한 내장 하네스 도구들과 함께 쓰여요. 하네스에 이미 내장된 도구가 있으니, 여러분은 도메인 특화 도구만 추가하면 되는 구조예요.

출처: 공식문서

기본 사용은 이렇게 생겼어요. 여러분이 만든 search, fetch_url, run_query 같은 도구를 tools=에 나열하면 되죠.

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[search, fetch_url, run_query],
)

커스텀 도구 (Custom tools)

일반 함수, LangChain @tool 데코레이터로 만든 함수, 또는 도구 딕트(tool dict) 같은 어떤 callable이든 tools=에 바로 넘길 수 있어요. Deep Agents는 함수 시그니처와 docstring에서 도구 스키마를 추론하기 때문에, 대부분의 경우 별도 스키마를 정의할 필요가 없어요.

Tavily로 웹 검색 도구를 만드는 예시를 볼게요.

import os
from typing import Literal
from tavily import TavilyClient
from deepagents import create_deep_agent

tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])


def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """Run a web search"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )


agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[internet_search],
)

LangChain 도구 정의와 사용법(tool dicts, StructuredTool, 반환 타입, 오류 처리 등)의 자세한 내용은 Tools 문서를 보세요.

MCP 도구

Deep Agents는 에이전트를 외부 서비스에 연결하는 개방 표준인 Model Context Protocol(MCP)을 완전히 지원해요. 어떤 MCP 서버에서든 도구를 불러와 create_deep_agent에 바로 넘길 수 있죠.

MCP는 에이전트가 데이터베이스, API, 파일시스템, 브라우저 등 점점 커지는 서버 생태계에 표준 인터페이스로 연결되게 해주는 개방형 프로토콜이에요. 서비스마다 커스텀 통합 코드를 짜는 대신, MCP 서버를 가리키기만 하면 Deep Agents가 그 서버가 노출하는 모든 도구를 가져와요.

MCP 서버에 연결하려면 mcp extra와 함께 LangChain을 설치해요.

pip install "langchain[mcp]"

import asyncio

from deepagents import create_deep_agent
from langchain.mcp import MCPAdapter


async def main():
    config = {"mcpServers": {"my_server": {"url": "http://localhost:8000/mcp"}}}
    async with MCPAdapter(config) as adapter:
        tools = await adapter.list_tools()
        agent = create_deep_agent(
            model="google_genai:gemini-3.6-flash",
            tools=tools,
        )
        await agent.ainvoke(
            {
                "messages": [
                    {"role": "user", "content": "Use the MCP server to help me."}
                ]
            },
            config={"configurable": {"thread_id": "1"}},
        )

stdio 서버, OAuth 인증, 도구 필터링, 상태 유지 세션 같은 자세한 설정 옵션은 전체 MCP 가이드를 보세요.

내장 하네스 도구 (Built-in harness tools)

여러분이 제공하는 도구에 더해, 모든 Deep Agent는 하네스에서 내장 도구 세트를 기본으로 갖고 출발해요.

도구	설명
`ls`	디렉터리 안의 파일 목록.
`read_file`	파일 내용 읽기 (페이지네이션과 멀티모달 지원).
`write_file`	새 파일 생성, 또는 기존 파일 덮어쓰기.
`edit_file`	파일 안에서 정확한 문자열 치환 수행.
`delete`	파일 또는 디렉터리와 내용을 재귀적으로 삭제. `delete` 도구는 `deepagents>=0.7`이 필요해요.
`glob`	glob 패턴과 맞는 파일 찾기.
`grep`	파일 내용 검색.
`execute`	셸 명령 실행 (샌드박스 백엔드만).
`task`	위임된 작업을 처리할 서브에이전트 생성.

write_todos로 구조화된 작업 계획을 추가하려면 TodoListMiddleware를 옵트인하면 돼요. 각 내장 도구가 정확히 무엇을 하는지에 대한 전체 설명은 Harness overview의 실행 환경 섹션을 보세요.

멀티모달 도구 출력

선택한 모델이 멀티모달 도구 결과를 지원하면, 커스텀 도구는 평문 텍스트나 표준 콘텐츠 블록(text, image, audio, video, file)을 반환할 수 있어요. 내장 read_file 도구도 지원되는 비텍스트 파일 타입에 대해 멀티모달 블록을 반환하죠.

텍스트 전용 결과는 문자열을 반환하면 되고, 텍스트와 미디어를 섞거나 인터리브된 멀티모달 출력은 콘텐츠 블록의 정렬된 리스트를 반환하면 돼요. 예시와 컨텍스트 압축 고려사항은 Multimodal과 Tool return values 문서를 참고하세요.

Deep Agents 도구