딥 에이전트 구축

종속성 업데이트

딥 에이전트 생성하려면 프로젝트의 pyproject.toml 파일 에 deepagents 패키지 추가합니다.

dependencies = [
    "deepagents==0.5.3",
    ... # other dependencies
]

deepagents 패키지 agent-engine-sdk-langgraph 패키지 의 선택적 종속성입니다. SDK는 앱 App.deep_agent() 함수를 호출할 때만 deepagents 패키지 가져오므로, 프로젝트 에서 명시적으로 선언해야 합니다.

기능 플래그 업데이트

agent.yaml 파일 에 다음 플래그를 추가하여 agent.yaml에서 심층 에이전트 기능을 활성화합니다.

features:
  deep_agent: true
  ... # other features

이 플래그는 도구 샌드박스에 딥 에이전트가 의존하는 내장 파일 시스템 및 셸 핸들러를 등록하도록 지시합니다.

매개변수

App.deep_agent() 메서드는 다음 매개 변수를 허용합니다:

스킬이 있는 딥 에이전트 생성

스킬을 호출하는 딥 에이전트 생성하려면 App.deep_agent() 메서드의 skills 매개변수에 스킬 디렉토리 경로 목록을 전달합니다.

다음 예시 @app.entrypoint-decorated 함수를 수정하여 단일 도구와 스킬 디렉토리 가진 딥 에이전트 생성합니다.

from agent_engine_sdk_langgraph import App
app = App()
@app.entrypoint
def build_agent():
    return app.deep_agent(
        llm=my_llm,
        tools=[my_tool],
        subagents=[],
        skills=["skills/security-review"],
    )

보안 유효성 검사

초기화 시 App.deep_agent() 메서드는 다음 검사를 실행하고 둘 중 하나가 실패하면 오류를 발생시킵니다.

• SubAgent 클래스에서 문자열 모델 참조 확인: 각 SubAgent.model 속성은 문자열이 아닌 LLM 인스턴스 여야 합니다. 문자열 모델 이름은 SecureWrappedLLM 클래스를 우회하며 플랫폼은 에이전트 거부합니다. 이 메서드는 최대 10 수준의 중첩을 확인합니다.

• 수동으로 제공한 backend 매개변수를 확인합니다: 플랫폼은 샌드박스를 소유하고 AgentEngineToolSandboxBackend 클래스를 백엔드 로 적용합니다. 사용자 지정 백엔드 제공하면 플랫폼의 샌드박스를 우회하고 플랫폼은 백엔드 거부합니다.

이러한 검사 외에도 App.deep_agent() 메서드는 deepagents 라이브러리가 그래프 를 컴파일하기 전에 llm 매개변수에 전달된 LLM 인스턴스 와 SecureWrappedLLM 클래스의 모든 SubAgent.model 속성을 자동으로 래핑합니다.

스킬 디렉토리 구조

스킬은 다음 디렉토리 구조 내에 있으며, 여기서 디렉토리 이름은 프런트매터의 name 필드 일치합니다.

<workspace-directory>/
└── skills/
    └── <skill-name>/
        └── SKILL.md

skills 매개변수에 전달된 스킬 경로는 에이전트의 작업 공간 디렉토리 agent.yaml 파일 포함된 디렉토리 기준으로 합니다.

스킬.md 형식

유효한 SKILL.md 파일 YAML 프론트매터로 시작해야 합니다. 다음 예시 는 유효한 SKILL.md 파일 의 템플릿입니다.

---
name: <skill-name>
description: <one-sentence description for LLM discovery>
---
# Skill Title
Detailed instructions or reference material for the agent...

YAML 프런트매터에 다음 필드를 포함해야 합니다.

상담원에게 스킬 전달

다음 예시 스킬 디렉토리 경로 목록을 App.deep_agent() 메서드에 전달합니다:

agent = app.deep_agent(
    llm=my_llm,
    tools=[],
    skills=["skills/security-review", "skills/style-guide"],
)

지원되는 작업

AgentEngineToolSandboxBackend 클래스 작업은 런타임 시 에이전트 에 의해 자동으로 호출되며 에이전트 작성자가 직접 호출하지 않습니다. AgentEngineToolSandboxBackend 클래스는 다음 작업을 지원하며, 각 작업은 해당 filesystem_* 또는 shell_execute 도구로 LLM에 노출됩니다.

Error Handling

백엔드 모든 오류를 분류한 후 에이전트 그래프 에 표시하여 에이전트 작업을 다시 시도할지 여부를 결정할 수 있도록 합니다. 다음 표에는 가능한 오류 분류와 그 원인이 나와 있습니다.

플랫폼은 오류 메시지가 에이전트 에 표시되기 전에 모든 내부 작업 공간 경로를 제거합니다.

Filesystem Sandbox

딥 에이전트는 샌드박스 파일 시스템 내에서 작동합니다. 샌드박스에는 다음과 같은 계층이 포함되어 있습니다.

• 쓰기 가능한 작업 공간(WORKSPACE_DIR): 기본값은 /tmp/agent-workspace 디렉토리 입니다. 에이전트 샌드박스 세션 중에 샌드박스는 WORKSPACE_DIR/.sessions/<session-hash>/ 경로에 대한 에이전트의 액세스 제한하여 동시 세션이 격리된 상태로 유지되도록 합니다. 생성된 파일에 대해 상대 경로 또는 /tmp 디렉토리 아래의 경로를 사용하세요.

• 읽기 전용 리소스 루트(READONLY_RESOURCE_ROOTS): AGENTIC_AGENT_WORKDIR 환경 변수와 skills/ 디렉토리 로 채워집니다. 이 계층을 통해 에이전트 세션별 작업 공간 내부 및 외부의 SKILL.md 파일을 읽을 수 있으므로 필요에 따라 스킬 콘텐츠를 로드할 수 있습니다.

# .env
AGENTIC_AGENT_WORKDIR=/app
# Do NOT add: WORKSPACE_DIR=/app