AI 에이전트 및 도구
에이전트와 도구는 앱 저장소의 .ironflock/ai-template.yml 파일에 정의됩니다.
에이전트 구조
각 최상위 키는 에이전트를 정의합니다:
my_agent:
tool_description: |
이 에이전트에 위임하는 시기와 제공해야 할 컨텍스트.
이는 에이전트가 아닌 IronFlock AI에 대한 지침입니다.
system_prompt: |
에이전트의 역할, 전문성, 가드레일을 정의합니다.
각 도구를 사용하는 시기와 예상 출력 형식을 설명합니다.
main: true
max_context_tokens: 50000
messages_after_summary: 6
max_iterations: 10
tools:
my_tool:
description: 이 도구의 역할과 호출 시기.
topic: my_app.my_wamp_topic
parameters:
my_param:
type: string
description: 이 파라미터가 제어하는 것.
required: true에이전트 필드
| 필드 | 설명 |
|---|---|
tool_description | 이 에이전트에 위임하는 시기에 대한 IronFlock AI의 지침. 내부 도구를 여기서 참조하지 마십시오. |
system_prompt | 에이전트의 역할, 전문성, 사용 가능한 도구, 예상 출력 형식을 정의합니다. |
main | true = IronFlock AI에게 표시됨. false = 서브 에이전트, 위임을 통해서만 접근 가능. |
max_context_tokens | 요청당 토큰 한도 (~단어당 1.3 토큰). |
messages_after_summary | 대화 이력에서 요약되지 않고 유지되는 최근 메시지 수. |
max_iterations | 에이전트가 중지하기 전 최대 도구 호출 라운드. 무한 루프를 방지합니다. |
도구 유형
WAMP 토픽 도구
이 도구는 엣지 코드에 등록된 WAMP 프로시저를 호출합니다:
tools:
get_sensor_data:
description: 디바이스에서 최신 센서 판독값을 가져옵니다.
topic: sensors.get_latest
parameters:
sensor_id:
type: string
description: 조회할 센서.
required: trueWAMP 토픽은 앱의 엣지 컴포넌트에 등록되어야 합니다. 반환 값은 AI가 해석할 수 있는 읽기 가능한 텍스트 또는 구조화된 데이터여야 합니다.
위임 도구
이 도구는 같은 파일에 정의된 다른 에이전트에 위임합니다:
tools:
configure_machine:
description: 복잡한 기계 구성 작업을 처리합니다.
delegate: machine_expert파라미터 유형
| 유형 | 설명 |
|---|---|
string | 텍스트 입력 |
number | 숫자 값 |
boolean | 참/거짓 |
object | 구조화된 JSON 객체 |
array | 값 목록 |
서브 에이전트 및 위임
복잡한 도메인의 경우 AI 통합을 여러 전문화된 에이전트로 분리합니다. 서브 에이전트는 집중된 작업을 처리하고 메인 에이전트가 오케스트레이션합니다.
메인 에이전트 vs. 서브 에이전트
| 속성 | 메인 에이전트 (main: true) | 서브 에이전트 (main: false) |
|---|---|---|
| 가시성 | IronFlock AI에 등록됨 | IronFlock AI에서 숨겨짐 |
| 접근 | IronFlock AI에 의해 직접 호출 | 다른 에이전트의 위임을 통해서만 접근 가능 |
| 활용 사례 | 앱의 AI 진입점 | 전문 도메인 전문성 |
서브 에이전트를 사용해야 하는 경우
다음과 같은 경우 서브 에이전트를 사용하십시오:
- 단일 에이전트에 너무 많은 도구가 있을 때 (8–10개 이상)
- 다른 작업이 다른 시스템 프롬프트나 전문성이 필요할 때
- 복잡한 워크플로우를 격리하고 싶을 때 (예: 구성 vs. 모니터링)
- 다른 작업에 다른 토큰 한도나 반복 횟수가 필요할 때
위임 흐름
사용자 → IronFlock AI → 메인 에이전트 → 서브 에이전트 → WAMP 도구 → 엣지 디바이스
↓
결과가 역방향으로 흐름메인 에이전트는 시스템 프롬프트와 위임 도구의 설명을 기반으로 위임 시기를 결정합니다. 서브 에이전트는 독립적으로 실행되고, 자체 도구를 사용하고, 결과를 메인 에이전트에 반환합니다. 메인 에이전트가 사용자에게 요약합니다.
모범 사례
도구 설명 작성
tool_description 필드는 IronFlock AI용 — 에이전트가 호출되는 시기를 결정합니다. IronFlock AI의 관점에서 작성하십시오:
좋은 예:
tool_description: |
사용자가 OPC UA 디바이스, PLC 구성 또는 산업 네트워크 스캔에 대해
질문할 때 이 에이전트에 위임하세요. 가능한 경우 디바이스 이름이나
네트워크 정보를 제공하세요.나쁜 예:
tool_description: |
저는 네트워크 스캔 및 PLC 구성이 가능한 OPC UA 전문가입니다.
제 도구에는 network_scan과 read_catalog가 포함됩니다.tool_description에서 내부 도구를 참조하지 마십시오 — IronFlock AI가 이를 알 필요가 없습니다.
시스템 프롬프트 작성
system_prompt는 에이전트의 동작을 정의합니다. 다음을 포함하십시오:
- 역할 — 에이전트가 무엇이고 무엇을 아는지.
- 사용 가능한 도구 — 각 도구와 사용 시기를 나열합니다.
- 출력 형식 — 응답이 어떻게 구조화되어야 하는지.
- 가드레일 — 에이전트가 하면 안 되는 것.
system_prompt: |
당신은 산업용 온도 모니터링을 위한 센서 데이터 전문가입니다.
사용 가능한 도구:
- get_reading: 현재 센서 값을 물을 때 사용
- get_history: 트렌드 또는 이력 데이터에 대해 물을 때 사용
- set_threshold: 알람 한도를 구성하도록 요청받을 때 사용
응답에는 항상 측정 단위를 포함하세요.
명시적인 사용자 확인 없이는 센서 임계값을 수정하지 마세요.
센서가 응답하지 않는 경우 디바이스 연결을 확인하도록 제안하세요.WAMP 도구 설계
- 읽기 가능한 데이터 반환 — AI 에이전트가 도구의 반환 값을 해석합니다. 원시 바이너리 데이터가 아닌 구조화된 텍스트 또는 JSON을 반환하십시오.
- 오류 메시지 포함 — 도구가 실패할 때 AI가 사용자에게 전달할 수 있는 설명적인 오류 메시지를 반환하십시오.
- 파라미터를 단순하게 유지 — 가능한 경우 기본 유형(
string,number,boolean)을 사용하십시오. 복잡한 중첩 객체는 AI가 올바른 호출을 구성하기 어렵게 만듭니다. - 필수 파라미터 표시 — 필수 입력에 항상
required: true를 설정하십시오.
에이전트 크기 조정
| 설정 | 권장 사항 |
|---|---|
max_context_tokens | 대부분 에이전트의 경우 30,000 – 50,000 |
messages_after_summary | 4 – 6 메시지 |
max_iterations | 5 – 10 (다단계 워크플로우는 늘림) |
값이 높을수록 더 복잡한 상호작용이 가능하지만 더 많은 토큰이 필요합니다. 보수적으로 시작하고 에이전트가 한도에 도달하면 늘리십시오.
에이전트 테스트
- 앱에 테스트 디바이스를 추가합니다.
- IronFlock AI 채팅을 엽니다.
- 에이전트를 트리거해야 하는 질문을 합니다.
- AI가 올바르게 위임하고 도구가 예상 데이터를 반환하는지 확인합니다.
- 오류 케이스 테스트 — 디바이스가 오프라인이거나 도구가 오류를 반환하면 어떻게 되나요?
완전한 예시
# 메인 에이전트 - IronFlock AI에게 표시됨
factory_agent:
main: true
tool_description: |
기계 구성 및 생산 모니터링을 포함한 공장 자동화 작업을 위해
이 에이전트에 위임하세요.
system_prompt: |
당신은 공장 자동화 어시스턴트입니다. 생산 라인을 모니터링하고
기계를 구성할 수 있습니다.
복잡한 기계 구성의 경우 configure_machine 도구를 사용하여
machine_config_agent에 위임하세요.
tools:
get_production_stats:
description: 현재 생산 통계를 가져옵니다.
topic: factory.stats
parameters:
line_id:
type: string
required: true
configure_machine:
description: 복잡한 기계 설정 및 구성을 처리합니다.
delegate: machine_config_agent
# 서브 에이전트 - 위임을 통해서만 접근 가능
machine_config_agent:
main: false
system_prompt: |
당신은 기계 구성 전문가입니다. 기계 파라미터를 읽고,
설정을 업데이트하고, 구성을 검증할 수 있습니다.
변경하기 전에 항상 현재 상태를 확인하세요.
적용하기 전에 사용자에게 변경 사항을 확인받으세요.
tools:
read_config:
description: 현재 기계 구성을 읽습니다.
topic: machines.read_config
parameters:
machine_id:
type: string
required: true
write_config:
description: 기계에 새 구성을 적용합니다.
topic: machines.write_config
parameters:
machine_id:
type: string
required: true
config:
type: object
description: 적용할 구성 키-값 쌍.
required: trueLast updated on