다양한 모델에서 잘 작동하도록 Deep Agents 튜닝하기

핵심 요약 (Key Takeaways)

💡**요약 (TL;DR): ** Deep Agents는 이전까지 여러 모델 제품군(model families) 전반에서 잘 작동하도록 일반적인 방식으로 설계되었습니다. 오늘 우리는 프롬프트(prompts), 도구(tools), 미들웨어(middleware)를 조정할 수 있는 모델별 프로필(model-specific profiles)을 추가합니다. 이를 통해 각 모델 제품군에 특화된 프롬프팅 가이드(prompting guides)를 더 잘 준수할 수 있습니다. 우리는 OpenAI, Anthropic, Google 모델을 위한 프로필을 즉시 사용할 수 있도록 제공하며, 이를 통해 tau2-bench의 일부 하위 집합에서 기본 하네스(default harness) 대비 10~20포인트의 성능 향상이 있음을 확인했습니다.

오늘 전까지 deepagents는 모든 거대 언어 모델(Large Language Models)에서 잘 작동하는 것을 목표로 하는 단일 프롬프트, 도구 및 미들웨어 세트로 제공되었습니다. 개발자들은 다른 모델로 교체하거나 시스템 프롬프트에 추가적인 도구 확장 기능을 더해 하네스를 확장할 수 있었습니다. 하지만 기본 프롬프트, 도구 및 미들웨어는 고정되어 있었으며 모델별로 최적화되지 않았습니다.

오늘부터 우리는 모델별로 이러한 파라미터(parameters)를 제어할 수 있는 방법으로 **하네스 프로필(harness profiles)**을 출시하게 되어 기쁩니다. 이것이 중요한 이유는 다음과 같습니다:

모델마다 프롬프팅 가이드(Prompting guides)가 다릅니다. OpenAI의 Codex 프롬프팅 가이드(Codex Prompting Guide)는 Codex 모델의 성능을 높일 수 있는 특정 도구 구현 및 이름(apply_patch, shell_command)을 규정합니다. Anthropic의 Claude 프롬프팅 가이드(prompting guidance)는 다른 일련의 관례를 강조합니다. 동일한 제품군 내에서도, Opus 4.6에서 4.7로의 마이그레이션 가이드(migration guide)는 수행할 가치가 있는 프롬프트 수준의 변경 사항을 지적합니다.

평가 리더보드(Eval leaderboards)를 보면 동일한 모델이라도 다른 하네스(harness)를 사용할 때 훨씬 다른 성능을 낼 수 있음을 보여줍니다. Terminal-Bench 2.0이 가장 명확한 공개 사례입니다. Claude Code 하네스는 Opus 4.6 제출물 중 최하위를 기록했습니다. 우리는 이전 작업인 '하네스 엔지니어링을 통한 Deep Agents 개선(Improving Deep Agents with harness engineering)'에서도 세심한 하네스 엔지니어링의 유사한 효과를 확인했습니다. 당시 우리는 프롬프트 및 미들웨어 훅(middleware hooks)과 같은 하네스 레이어 변경 사항을 적용하는 것만으로 Terminal-Bench 2.0에서 gpt-5.2-codex의 성능을 52.8%에서 66.5%로 끌어올렸습니다 (발표 당시 Top 30에서 Top 5로 진입).

단일 하네스가 모든 모델에 최적일 수는 없습니다. 따라서 우리는 모델별로 하네스를 다양하게 지원할 수 있도록 쉽게 만들었습니다.

이것이 얼마나 중요할까요?

프로필 효과 측정 결과

이것이 얼마나 중요한지 판단하기 위해, 우리는 tau2-bench(멀티턴 도구 사용 (multi-turn tool use) + 지시 이행 (instruction following))의 하위 집합에서 성능을 측정했습니다. 우리는 프론티어 모델 (frontier models)이 아직 포화 상태에 도달하지 않은 더 어려운 작업들로 구성된 선별된 하위 집합을 사용하여, 하네스 (harness) 수준의 변화가 에이전트 (agents)에 미치는 영향을 더 잘 측정할 수 있도록 했습니다.

모델별 변경 사항

우리는 프로필별로 적용한 변경 사항의 근거로 Codex 및 Claude 프롬프팅 가이드 (prompting guides)를 사용했습니다.

Codex의 경우 주요 변경 사항은 다음과 같습니다:

도구 변경 사항 (Tool changes): deepagents 내의 기본 edit_file 구현을 권장되는 apply_patch 도구로 재정의(overriding)하고, deepagents 내의 execute 도구 이름을 shell_command로 별칭(aliasing) 지정했습니다.

프롬프트 변경 사항 (Prompt changes): 주로 프롬프팅 가이드의 세부 정보를 사용하여 도구 호출 (tool calling) 및 계획 (planning)과 관련된 내용입니다.

모든 도구 호출을 하기 전에, 당신이 필요로 할 모든 파일과 리소스를 결정하십시오. 읽기, 검색 및 기타 독립적인 작업들을 한 번에 하나씩 실행하는 대신 병렬 도구 호출 (parallel tool calls)로 배치(batch) 처리하십시오.

Opus의 경우 주요 변경 사항은 모두 도구 사용 및 계획에 초점을 맞춘 프롬프팅이었습니다. 예를 들어, 아래는 프롬프트에 추가된 두 개의 스니펫 (snippets)입니다.

<tool_result_reflection>

도구 결과 (tool results)를 받은 후, 진행하기 전에 그 품질을 주의 깊게 반추(reflect)하고 최적의 다음 단계를 결정하십시오. 이 새로운 정보를 바탕으로 계획하고 반복(iterate)하기 위해 당신의 사고(thinking)를 사용한 다음, 최선의 다음 행동을 취하십시오.

</tool_result_reflection>

<tool_usage>

작업이 파일, 테스트 또는 시스템 출력의 상태에 의존하는 경우, 그것이 무엇을 포함하고 있을지에 대해 기억에 의존하여 추론하기보다 도구를 사용하여 해당 상태를 직접 관찰하십시오. 파일을 설명하기 전에 파일을 읽으십시오. 테스트가 통과했다고 주장하기 전에 테스트를 실행하십시오. 심볼 (symbol)이 존재하는지 또는 존재하지 않는지 단언하기 전에 코드베이스 (codebase)를 검색하십시오. 도구를 사용한 능동적인 조사 (Active investigation)는 기본 작업 모드이며, 차선책 (fallback)이 아닙니다.

</tool_usage>

우리의 결론은 모델별로 하네스 (harness)를 커스터마이징할 수 있는 인터페이스를 제공하는 것이, 빌더들이 에이전트 (agent)별 프로필 (profile)을 관리하고, 버전을 관리하며, 구성 (configuration)의 차이를 쉽게 테스트할 수 있게 해주는 유용한 기본 요소 (primitive)라는 점입니다.

지금 바로 사용해 보세요

지금 바로 사용하려면, 단순히 다음을 시작하면 됩니다:

deepagents: uv add deepagents

agent = create_deep_agent(
model="google_genai:gemini-3.1-pro-preview",
tools=[internet_search],
...

지원되는 모델에 대해서는 프로필이 자동으로 적용됩니다. 현재 각 기본 프로필이 구체적으로 어떻게 구성되어 있는지 자세히 알고 싶다면, 리포지토리 (repo)의 코드를 검사할 수 있습니다. 자신만의 프로필을 등록하는 방법을 배우려면 계속 읽어주세요.

프로필의 내부 작동 원리

하네스 프로필 (harness profile)은 모델마다 달라지는 하네스의 부분들, 즉 시스템 프롬프트 접두사/접미사 (system prompt prefix/suffix), 도구 포함 및 명명 (tool inclusion and naming), 미들웨어 선택 (middleware selection), 서브에이전트 구성 (subagent configuration), 그리고 기술 (skills)을 위한 선언적 오버라이드 (declarative override) 계층입니다. 모델이나 제공자 (provider)에 대한 프로필을 등록하거나 (또는 YAML에서 기존 프로필을 로드하거나), 모델을 교체할 때 create_deep_agent가 그에 맞춰 적응합니다. 중요한 점은, 호출부 (call site)가 변경되지 않는다는 것입니다.

우리는 OpenAI, Anthropic, 그리고 Google 모델을 위한 기본값 (defaults)을 제공합니다. 이를 오버라이드하거나, 그 위에 자신만의 프로필을 계층화하거나, 플러그인 (plugin)으로서 프로필을 배포할 수 있습니다.

from deepagents import (
HarnessProfile,
register_harness_profile,
...

또는 YAML에서 프로필을 선언할 수 있습니다:

# openai.yaml
base_system_prompt: You are helpful.
system_prompt_suffix: Respond briefly.
...

더 자세한 커스텀 사항은 프로필 (Profiles) 문서를 참조하여 전체 필드 범위 (field surface), 병합 의미론 (merge semantics), 그리고 플러그인 패키징 (plugin packaging)을 확인하세요. 사용하는 모델에 대해 시작 시점에 프로필을 등록하거나, 우리가 제공하는 내장 프로필을 사용하면 됩니다.

Deep Agents를 기반으로 구축하면서 프로필을 공유하고 싶다면, PR(Pull Request)을 보내거나 entry points를 통해 플러그인 (plugin) 형태로 배포하세요. 저희는 모델 전반에 걸쳐 프로필 인터페이스 (profile surface)를 계속 확장해 나갈 것입니다. 저희의 목표는 여러분이 어떤 모델을 선택하더라도, Deep Agents가 여러분의 작업에 가장 적합한 하네스 (harness)를 만들 수 있도록 도구와 기본 설정 (defaults)을 제공하는 것입니다. 개발자들이 자신의 작업에 맞춰 에이전트 하네스 (agent harness)를 어떻게 커스텀할 수 있는지 보여주는 더 많은 정보와 워크스루 (walkthroughs)를 출시할 예정입니다.