프로파일

프로파일 (Profiles)

딥 에이전트는 특정 공급자나 특정 모델을 선택할 때마다 적용할 설정을 **하네스 프로파일(harness profile)**로 묶어 둘 수 있어요. 시스템 프롬프트 조정, 툴 설명 덮어쓰기, 제외할 툴·미들웨어, 추가 미들웨어, 범용 서브에이전트 편집까지 한 곳에서 관리할 수 있죠. 이게 특정 모델에 맞춰 create_deep_agent 호출 지점을 바꾸지 않고 하네스 동작을 조정하는 주된 방법이에요.

출처: 공식문서

하네스 프로파일

HarnessProfile은 프롬프트 조립, 툴 가시성, 미들웨어, 기본 서브에이전트 조정을 설명하는데, create_deep_agent이 채팅 모델을 구성한 뒤에 이걸 적용해요.

from deepagents import (
    GeneralPurposeSubagentProfile,
    HarnessProfile,
    register_harness_profile,
)

register_harness_profile(
    "openai:gpt-5.5",
    HarnessProfile(
        system_prompt_suffix="Respond in under 100 words.",
        excluded_tools={"execute"},
        excluded_middleware={"SummarizationMiddleware"},
        general_purpose_subagent=GeneralPurposeSubagentProfile(enabled=False),
    ),
)

주요 필드를 보면 이렇게 돼요.

  • base_system_prompt — Deep Agents 기본 시스템 프롬프트(시스템 프롬프트의 base 키)를 교체해요.
  • system_prompt_suffix — 호출자의 suffix 뒤에 텍스트를 붙이고 조립된 시스템 프롬프트의 마지막에 배치해요. 메인 에이전트, 선언적 서브에이전트, 자동 추가된 범용 서브에이전트에 모두 적용돼요.

excluded_middleware에 FilesystemMiddleware, SubAgentMiddleware, 내부 권한 미들웨어를 나열하면 ValueError가 발생해요. 이들은 Deep Agents 스택에서 필수 스캐폴딩이기 때문이에요. 미들웨어는 두 가지 방식으로 지정할 수 있어요. 하나는 미들웨어 클래스(정확한 타입으로 매칭) 또는 AgentMiddleware.name과 일치하는 일반 문자열이고("SummarizationMiddleware"처럼 빌트인이나 공개 별칭에 씀), 다른 하나는 module:Class 임포트 참조(예: "my_pkg.middleware:TelemetryMiddleware")로 설정 파일에서 정확한 미들웨어 클래스를 겨냥하는 방식이에요. 임포트 참조는 지연(lazily) 해석되므로, 신뢰하는 로컬 설정에만 쓰세요. 로드하면 Python 코드를 임포트하기 때문이에요.

공급자 프로파일 (Provider profiles)

ProviderProfile은 딥 에이전트를 만들 때 provider:model 문자열을 제공할 때만 적용돼요. init_chat_model로 미리 구성된 모델을 넘길 때는 적용되지 않아요.

from deepagents import ProviderProfile, register_provider_profile

register_provider_profile(
    "openai",
    ProviderProfile(init_kwargs={"temperature": 0}),
)

설정 파일에서 프로파일 로드하기

YAML/JSON 기반 워크플로라면 HarnessProfileConfig를 써요. 이 클래스는 HarnessProfile의 선언적 하위 집합(프롬프트 텍스트, 툴 설명 덮어쓰기, 제외할 툴·미들웨어, 범용 서브에이전트 편집)을 미러링하고 to_dict / from_dict를 제공해요.

import yaml
from deepagents import HarnessProfileConfig, register_harness_profile

with open("openai.yaml") as f:
    register_harness_profile(
        "openai",
        HarnessProfileConfig.from_dict(yaml.safe_load(f)),
    )

프로파일을 플러그인으로 배포하기

프로파일을 플러그인으로 묶어서 배포할 수도 있어요.

from deepagents import (
    HarnessProfile,
    ProviderProfile,
    register_harness_profile,
    register_provider_profile,
)


def register_harness() -> None:
    register_harness_profile(
        "my_provider",
        HarnessProfile(system_prompt_suffix="Batch independent tool calls in parallel."),
    )


def register_provider() -> None:
    register_provider_profile(
        "my_provider",
        ProviderProfile(init_kwargs={"temperature": 0}),
    )

더 알아보기 (Learn more)