프로필

프로필 (Profiles)

Deep Agents가 모델이 선택될 때 적용하는 프로바이더별·모델별 기본값을 패키징하세요.

하네스 프로필(Harness profiles) 은 특정 모델이나 프로바이더에 맞게 Deep Agents 하네스를 커스터마이즈할 수 있게 해줘요. 시스템 프롬프트와 도구 설명을 조정하고, 도구나 미들웨어를 제외하고, 미들웨어를 추가하고, 범용 서브에이전트를 구성할 수 있습니다. Deep Agents는 일치하는 모델을 선택할 때마다 에이전트 생성 코드를 변경하지 않고도 이 설정을 적용합니다.

출처: 문서

본문

프로바이더 프로필(모델 생성에 사용되는 설정 제어용)과 플러그인 등록 시스템은 Python 전용 기능입니다. TypeScript SDK는 하네스 프로필만 지원합니다.

하네스 프로필 (Harness profiles)

Deep Agents에는 특정 프로바이더와 모델에 대한 기본 설정이 있는 내장 하네스 프로필이 포함됩니다.

HarnessProfileOptions을 사용해 createDeepAgent가 채팅 모델을 구성한 후 적용하는 설정을 정의하세요:

import { registerHarnessProfile } from "deepagents";

registerHarnessProfile("openai:gpt-6-astra", {
  systemPromptSuffix: "Respond in under 100 words.",
  excludedTools: ["execute"],
  excludedMiddleware: ["SummarizationMiddleware"],
  generalPurposeSubagent: { enabled: false },
});
  • baseSystemPrompt (string) — 프로필의 기본 지침을 설정. 메인 에이전트의 경우 호출자의 시스템 지침을 따릅니다; 기본적으로 기본 지침이 추가되지 않습니다. 선언적 서브에이전트의 경우 작성된 시스템 프롬프트를 대체합니다.
  • systemPromptSuffix (string) — 호출자의 지침과 프로필의 기본 지침 뒤에 텍스트를 추가. 메인 에이전트, 선언적 서브에이전트, 자동 추가된 범용 서브에이전트에 적용됩니다.
  • toolDescriptionOverrides (Record<string, string>) — 도구 이름 키로 개별 도구 설명을 재정의.
  • excludedTools (string[]) — 도구 세트에서 특정 하네스 수준 도구 제거. 도구 이름으로 일치하며, 사용자 제공 및 미들웨어 제공 도구 모두를 잡는 post-injection 필터로 적용.
  • excludedMiddleware (string[]) — 조립된 스택에서 특정 미들웨어 제거. 각 미들웨어의 .name 속성과 일치. 필수 스캐폴딩 이름(FilesystemMiddleware, SubAgentMiddleware)은 포함할 수 없음.
  • extraMiddleware (AgentMiddleware[] | (() => AgentMiddleware[])) — 사용자 미들웨어 뒤 스택에 추가되는 추가 미들웨어. 정적 배열 또는 에이전트 구성마다 새 인스턴스를 반환하는 인자 없는 팩토리 가능.
  • generalPurposeSubagent (GeneralPurposeSubagentConfig) — 범용 서브에이전트 비활성화, 이름 변경, 재프롬프트 (enabled, description, systemPrompt).
호출자가 제공한 `systemPrompt`는 선택된 모델과 관계없이 항상 조립된 프롬프트의 맨 앞에 있고, `systemPromptSuffix`는 항상 맨 끝에 있습니다. 동일한 오버레이 규칙이 서브에이전트에도 적용됩니다: 각 서브에이전트는 자신의 모델에 대해 프로필 해석을 다시 실행합니다. 커스텀 지침과 서브에이전트 프롬프트 동작은 [시스템 프롬프트](/oss/javascript/deepagents/customization#system-prompt)를 참고하세요. `excludedMiddleware`에 `FilesystemMiddleware` 또는 `SubAgentMiddleware`를 나열하면 생성 시 throw합니다—이들은 필수 스캐폴딩입니다. 미들웨어를 제거하지 않고 도구를 모델에서 숨기려면 `excludedTools`를 사용하세요.

프로필을 에이전트 생성 전에 등록하세요. 모델 문자열 또는 직접 구성한 모델 객체를 전달하세요; 예시는 모델 파라미터 구성을 참고하세요. 하네스 프로필은 두 경우 모두에 적용됩니다.

사전 구성된 모델 인스턴스의 조회 순서: 모델 객체를 전달하면 하네스는 그 객체가 보고하는 프로바이더와 식별자를 사용해 프로필을 조회합니다.

  1. 식별자에 콜론이 없으면 provider:identifier를 조회하고, 실패 시 그 프로바이더의 기본값으로 폴백.
  2. 식별자에 콜론이 있으면 직접 조회하고, 실패 시 접두사의 기본값으로 폴백.
  3. 어느 쪽도 일치하지 않으면 보고된 프로바이더의 기본값 사용.

등록 키 (Registration keys)

프로필 등록은 다음 키를 사용합니다:

  • 프로바이더 수준 — "openai" 같은 bare 프로바이더 이름은 그 프로바이더의 모든 모델에 적용.
  • 모델 수준 — "openai:gpt-6-astra" 같은 정규화된 provider:model 키는 해당 특정 모델에만 적용.

프로바이더 수준과 모델 수준 프로필이 모두 존재하면 해석 시 병합됩니다. 설정되지 않은 모델 수준 필드는 프로바이더 수준 프로필에서 상속되고, 명시적 모델 수준 값이 이를 덮어씁니다.

TypeScript의 프로필 등록은 콜론을 포함한 모델 식별자를 지원하지 않습니다. 프로바이더와 모델 식별자를 구분하는 단일 콜론이 있는 my_provider:my-model 같은 키를 사용하세요.

예를 들어, 가상 프로바이더의 모델에 대해 도구를 제외한 다음 한 모델의 프롬프트 접미사를 커스터마이즈합니다:

import { registerHarnessProfile } from "deepagents";

// Set defaults for a hypothetical provider.
registerHarnessProfile("my_provider", {
  excludedTools: ["execute"],
  systemPromptSuffix: "Respond in under 500 words.",
});

// Override the prompt suffix for one model; inherit the excluded tool.
registerHarnessProfile("my_provider:my-model", {
  systemPromptSuffix: "Respond in under 100 words.",
});

모델별 등록을 사용하는 에이전트는 execute를 제외하고 100단어 접미사를 받습니다. my_provider의 다른 모델은 execute를 제외하고 500단어 접미사를 받습니다.

기존 키로 다시 등록하면 새 프로필이 이전 것 위에 병합됩니다. 대체하지 않습니다. 이는 또한 내장 프로필의 키로 등록하여 커스터마이즈할 수 있게 해줍니다. 필드별 규칙은 병합 의미론을 참고하세요.

예시를 계속해서, 같은 모델에 도구 하나를 더 제외합니다:

registerHarnessProfile("my_provider:my-model", {
  excludedTools: ["grep"],
});

이 모델로 나중에 생성된 에이전트는 execute와 grep을 모두 제외하고 100단어 접미사를 유지합니다. 다른 모델은 프로바이더 기본값을 유지합니다.

모든 프로바이더와 일치하는 와일드카드 키는 없습니다. 어디에나 동일한 재정의를 적용하려면 — 예를 들어 선택된 모델과 관계없이 `SummarizationMiddleware`를 빼려면 — 사용하는 각 프로바이더 키로 프로필을 등록하세요. 프로필은 선택되는 모델에 의존하는 조정을 위한 것입니다. 모델과 무관하게 적용되어야 하는 전역 조정은 `createDeepAgent` 호출 지점에서 해야 합니다.

병합 의미론 (Merge semantics)

필드 병합 동작
baseSystemPrompt, systemPromptSuffix 설정되면 새 값이 우선; 그렇지 않으면 상속
toolDescriptionOverrides 매핑이 키별로 병합; 공유 키에서는 새 값이 우선
excludedTools, excludedMiddleware 세트 합집합
extraMiddleware 이름으로 병합: 새 인스턴스가 기존 위치를 대체, 새 항목은 추가
generalPurposeSubagent 필드별 병합 (설정되지 않은 필드는 상속)

프로바이더 프로필 (Provider profiles)

프로바이더 프로필(temperature 같은 모델 생성에 사용되는 설정 제어용)은 Python 전용 기능이며 TypeScript SDK에서는 사용할 수 없습니다.

구성 파일에서 프로필 로드

YAML/JSON 기반 워크플로의 경우 parseHarnessProfileConfig를 사용하세요. camelCase 키를 가진 일반 객체에서 HarnessProfile을 검증하고 구축합니다. extraMiddleware 인스턴스 같은 런타임 전용 상태는 JSON/YAML로 표현할 수 없으며 프로그래밍 방식으로 설정해야 합니다.

# profile.yaml
baseSystemPrompt: You are helpful.
systemPromptSuffix: Respond briefly.
excludedTools:
  - execute
  - grep
excludedMiddleware:
  - SummarizationMiddleware
generalPurposeSubagent:
  enabled: false

import { readFileSync } from "fs";
import YAML from "yaml";
import { parseHarnessProfileConfig, registerHarnessProfile } from "deepagents";

const raw = YAML.parse(readFileSync("profile.yaml", "utf-8"));
registerHarnessProfile("openai", parseHarnessProfileConfig(raw));

프로필을 JSON/YAML로 다시 직렬화하려면 serializeProfile을 사용하세요:

import { serializeProfile } from "deepagents";

const data = serializeProfile(profile); // JSON-compatible object

비어 있지 않은 extraMiddleware가 있는 프로필은 직렬화할 수 없습니다; 미들웨어 인스턴스가 있으면 serializeProfile은 throw합니다.

프로필을 플러그인으로 제공

플러그인 등록 시스템(패키지 엔트리 포인트 경유)은 Python 전용 기능입니다. TypeScript에서는 애플리케이션 시작 시 또는 패키지 초기화 코드에서 registerHarnessProfile을 직접 호출하세요.

더 알아보기