Onyx v4 operator lesson 05 · standalone operator lesson

Agents와 Actions/MCP

Agent의 지시문, 지식 범위, 실행 권한을 각각 좁혀 외부 작업을 안전하게 붙이는 절차입니다.

이 lesson의 목적

Agent의 지시문, 지식 범위, 실행 권한을 각각 좁혀 외부 작업을 안전하게 붙이는 절차입니다.

주 대상: 업무별 Agent 관리자, 도구 연동 담당자, MCP/OpenAPI 실행권한 승인자

반복 업무를 특정 Agent로 나누고 싶을 때
Internal Search/Web Search/Code Execution/Image Generation 같은 Actions를 업무별로 허용할 때
MCP 또는 OpenAPI로 외부 시스템 작업을 붙일 때

Agent가 해결할 반복 업무와 금지할 업무를 한 문장으로 정해야 합니다.
Agent에 줄 Knowledge 범위와 Actions 범위가 준비되어야 합니다.
MCP 서버는 HTTP transport로 접근 가능해야 하며, stdio 연결은 Onyx MCP client에서 지원하지 않는 것으로 문서화되어 있습니다.

Agent는 instructions, knowledge, actions 조합입니다. 먼저 한 업무만 좁게 씁니다.

주의: “모든 질문 처리” Agent는 지식과 도구 범위가 커져 검증이 어렵습니다.

필요한 문서/Connector/File Upload만 연결합니다.

주의: 문서가 많을수록 항상 좋은 것이 아니라 신뢰성과 성능이 떨어질 수 있습니다.

Internal Search, Web Search, Code Execution, Image Generation은 구성 필요 여부와 Provider가 다릅니다.

주의: 사용자 입력창에서 켜고 끌 수 있는 권한과 Admin 기본 허용을 구분합니다.

공유 인증과 사용자별 인증 중 어느 쪽이 업무 권한과 맞는지 정합니다.

주의: 공유 키는 모든 사용자가 같은 외부 권한을 갖는 효과가 있습니다.

Admin Panel → MCP Actions에서 Server Name, Description, MCP Server URL을 입력합니다. 서버는 추가 직후 disconnected 상태입니다.

주의: 추가 버튼 클릭만으로 사용 가능 상태가 아닙니다.

No Auth, API Key, OAuth, Pass-through OAuth 중 하나를 선택하고 Connect로 도달성과 인증을 검증합니다.

주의: OAuth/DCR 여부, Client ID/Secret 필요 여부를 외부 MCP 서버 정책과 맞춥니다.

MCP Actions dashboard에서 Agent가 사용할 tool subset을 선택합니다.

주의: 서버의 모든 tool을 그대로 열면 Agent 행동 범위가 넓어집니다.

Agent에게 어떤 도구를 쓸 수 있고 어떤 작업은 못 하는지 설명하게 한 뒤, 안전한 테스트 action으로 결과를 확인합니다.

주의: 답변 생성과 외부 실행 성공을 같은 PASS로 합치지 않습니다.

아래 문서는 이 정적 lesson의 작성 근거입니다. 실제 화면 라벨이나 배포 성공은 별도 현장 검증이 필요합니다.

이 페이지는 Actions/MCP 운영 절차입니다. 외부 시스템에 실제 쓰기 작업을 수행하지 않으며, 권한·감사·비용 정책은 조직별 승인이 필요합니다.