에이전트 기술은 에이전트 에 특수한 기능 및 도메인 전문 지식을 제공하는 지침, 스크립트 및 리소스의 이식 가능한 패키지입니다. 기술은 개방형 사양을 따르고 점진적 공개 패턴을 구현하므로 에이전트는 필요할 때 필요한 컨텍스트만 로드합니다.
다음을 수행하려는 경우 에이전트 기술을 사용합니다.
- 패키지 도메인 전문 지식 - 재사용 가능한 이식 가능한 패키지로 전문 지식(비용 정책, 법적 워크플로, 데이터 분석 파이프라인)을 캡처합니다.
- 에이전트 기능 확장 - 핵심 지침을 변경하지 않고 에이전트에게 새로운 기능을 제공합니다.
- 일관성 보장 - 다단계 작업을 반복 가능하고 감사 가능한 워크플로로 전환합니다.
- 상호 운용성 활성화 - 다양한 대리 기술 호환 제품에서 동일한 기술을 재사용합니다.
기술 구조
기술은 리소스에 대한 선택적 하위 디렉터리가 있는 파일을 포함하는 SKILL.md 디렉터리입니다.
expense-report/
├── SKILL.md # Required — frontmatter + instructions
├── scripts/
│ └── validate.py # Executable code agents can run
├── references/
│ └── POLICY_FAQ.md # Reference documents loaded on demand
└── assets/
└── expense-report-template.md # Templates and static resources
SKILL.md 형식
파일에는 SKILL.md YAML 프런트매터와 markdown 콘텐츠가 있어야 합니다.
---
name: expense-report
description: File and validate employee expense reports according to company policy. Use when asked about expense submissions, reimbursement rules, or spending limits.
license: Apache-2.0
compatibility: Requires python3
metadata:
author: contoso-finance
version: "2.1"
---
| 분야 | 필수 | Description |
|---|---|---|
name |
네 | 최대 64자 소문자, 숫자 및 하이픈만 해당됩니다. 하이픈으로 시작하거나 끝내거나 연속 하이픈을 포함해서는 안 됩니다. 부모 디렉터리 이름과 일치해야 합니다. |
description |
네 | 기술이 수행하는 기능 및 사용 시기. 최대 1024자 에이전트가 관련 작업을 식별하는 데 도움이 되는 키워드를 포함해야 합니다. |
license |
아니오 | 번들된 라이선스 파일에 대한 라이선스 이름 또는 참조입니다. |
compatibility |
아니오 | 최대 500자 환경 요구 사항(의도된 제품, 시스템 패키지, 네트워크 액세스 등)을 나타냅니다. |
metadata |
아니오 | 추가 메타데이터에 대한 임의의 키-값 매핑입니다. |
allowed-tools |
아니오 | 기술이 사용할 수 있는 미리 승인된 도구의 공간으로 구분된 목록입니다. 실험적 - 지원은 에이전트 구현마다 다를 수 있습니다. |
프런트매터 뒤의 markdown 본문에는 단계별 지침, 입력 및 출력 예제, 일반적인 에지 사례 또는 에이전트가 작업을 수행하는 데 도움이 되는 콘텐츠와 같은 기술 지침이 포함되어 있습니다. 500줄 미만으로 유지하고 SKILL.md 자세한 참조 자료를 별도의 파일로 이동합니다.
점진적 공개
에이전트 기술은 3단계 점진적 공개 패턴을 사용하여 컨텍스트 사용을 최소화합니다.
- Advertise (기술당 최대 100개 토큰) - 각 실행이 시작될 때 기술 이름과 설명이 시스템 프롬프트에 삽입되므로 에이전트는 사용 가능한 기술을 알 수 있습니다.
-
로드 (< 권장 토큰 5,000개) - 작업이 기술의 도메인과 일치하면 에이전트는 도구를 호출
load_skill하여 자세한 지침과 함께 전체 SKILL.md 본문을 검색합니다. -
필요한 경우 리소스 읽기 - 에이전트는 필요한 경우에만 보조 파일(참조, 템플릿, 자산)을 가져오기 위해 도구를 호출
read_skill_resource합니다.
이 패턴은 에이전트의 컨텍스트 창을 간결하게 유지하면서 요청 시 심층 도메인 지식에 액세스할 수 있도록 합니다.
FileAgentSkillsProvider 사용
파일 FileAgentSkillsProvider 시스템 디렉터리에서 기술을 검색하여 에이전트가 컨텍스트 공급자로 사용할 수 있도록 합니다. 구성된 경로를 재귀적으로(최대 2개의 수준 깊이까지) SKILL.md 검색하고, 파일의 형식과 리소스의 유효성을 검사하고, 두 가지 도구를 에이전트 load_skillread_skill_resource에 노출합니다.
비고
FileAgentSkillsProvider에서는 아직 스크립트 실행이 지원되지 않으며, 향후 릴리스에서 추가될 예정입니다.
기본 설정
FileAgentSkillsProvider 기술을 포함하는 디렉터리를 가리키도록 만들고 에이전트의 컨텍스트 공급자에 추가합니다.
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
// Discover skills from the 'skills' directory
var skillsProvider = new FileAgentSkillsProvider(
skillPath: Path.Combine(AppContext.BaseDirectory, "skills"));
// Create an agent with the skills provider
AIAgent agent = new AzureOpenAIClient(
new Uri(endpoint), new DefaultAzureCredential())
.GetResponsesClient(deploymentName)
.AsAIAgent(new ChatClientAgentOptions
{
Name = "SkillsAgent",
ChatOptions = new()
{
Instructions = "You are a helpful assistant.",
},
AIContextProviders = [skillsProvider],
});
에이전트 호출
구성되면 에이전트는 사용 가능한 기술을 자동으로 검색하고 작업이 일치할 때 사용합니다.
// The agent loads the expense-report skill and reads the FAQ resource
AgentResponse response = await agent.RunAsync(
"Are tips reimbursable? I left a 25% tip on a taxi ride.");
Console.WriteLine(response.Text);
기본 설정
FileAgentSkillsProvider을 생성하여 당신의 기술을 포함하는 디렉터리를 가리키게 하고, 에이전트의 컨텍스트 공급자에 추가합니다.
from pathlib import Path
from agent_framework import FileAgentSkillsProvider
from agent_framework.azure import AzureOpenAIChatClient
from azure.identity.aio import AzureCliCredential
# Discover skills from the 'skills' directory
skills_provider = FileAgentSkillsProvider(
skill_paths=Path(__file__).parent / "skills"
)
# Create an agent with the skills provider
agent = AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
name="SkillsAgent",
instructions="You are a helpful assistant.",
context_providers=[skills_provider],
)
에이전트 호출
구성되면 에이전트는 사용 가능한 기술을 자동으로 검색하고 작업이 일치할 때 사용합니다.
# The agent loads the expense-report skill and reads the FAQ resource
response = await agent.run(
"Are tips reimbursable? I left a 25% tip on a taxi ride."
)
print(response.text)
여러 기술 디렉터리
경로 목록을 전달하여 여러 디렉터리를 검색할 수 있습니다.
var skillsProvider = new FileAgentSkillsProvider(
skillPaths: [
Path.Combine(AppContext.BaseDirectory, "company-skills"),
Path.Combine(AppContext.BaseDirectory, "team-skills"),
]);
skills_provider = FileAgentSkillsProvider(
skill_paths=[
Path(__file__).parent / "company-skills",
Path(__file__).parent / "team-skills",
]
)
각 경로는 개별 기술 폴더(포함 SKILL.md) 또는 기술 하위 디렉터리가 있는 부모 폴더를 가리킬 수 있습니다. 공급자는 최대 2단계 깊이로 검색합니다.
사용자 지정 시스템 프롬프트
기본적으로 FileAgentSkillsProvider는 사용 가능한 기술 목록을 나열하고 에이전트에게 load_skill 및 read_skill_resource를 사용하도록 지시하는 시스템 프롬프트를 삽입합니다. 이 프롬프트를 사용자 지정할 수 있습니다.
var skillsProvider = new FileAgentSkillsProvider(
skillPath: Path.Combine(AppContext.BaseDirectory, "skills"),
options: new FileAgentSkillsProviderOptions
{
SkillsInstructionPrompt = """
You have skills available. Here they are:
{0}
Use the `load_skill` function to get skill instructions.
Use the `read_skill_resource` function to read skill files.
"""
});
비고
사용자 지정 템플릿에는 기술 목록이 삽입된 자리 표시자가 포함되어 {0} 야 합니다. 리터럴 중괄호는 다음과 같이 {{}}이스케이프되어야 합니다.
skills_provider = FileAgentSkillsProvider(
skill_paths=Path(__file__).parent / "skills",
skills_instruction_prompt=(
"You have skills available. Here they are:\n{0}\n"
"Use the `load_skill` function to get skill instructions.\n"
"Use the `read_skill_resource` function to read skill files."
),
)
비고
사용자 지정 템플릿에는 기술 목록이 삽입된 자리 표시자가 포함되어 {0} 야 합니다.
보안 고려 사항
FileAgentSkillsProvider 는 파일 시스템의 정적 콘텐츠만 읽고 다음 보안 조치를 포함합니다.
- XML 이스케이프 — 기술 메타데이터(이름 및 설명)는 시스템 프롬프트에 삽입되기 전에 XML 이스케이프되어 기술 프런트매터를 통한 프롬프트 삽입을 방지합니다.
- 경로 순회 보호 - 리소스 읽기는 파일 경로가 스킬 디렉토리 내에 계속 머물도록 확인하여 이스케이프 시도를 차단합니다.
- Symlink 가드 - 각 경로 세그먼트가 스킬 디렉터리 외부로 해석될 수 있는 심볼릭 링크를 검사합니다.
- 검색 시 유효성 검사 - 기술이 로드될 때 참조된 모든 리소스의 유효성이 검사됩니다. 누락되거나 잘못된 리소스가 있는 기술은 제외되고 기록됩니다.
경고
신뢰할 수 있는 원본의 기술만 사용합니다. 기술 지침은 에이전트의 컨텍스트에 삽입되며 에이전트 동작에 영향을 줄 수 있습니다.