어떤 경험을 사용 중인가요?
이 문서는 두 가지 경험을 모두 다룹니다. Settings → Personal → My Okou를 사용할 수 있으면 My Okou 단계를 따르세요. New agent가 있는 Agents 페이지를 사용한다면 Legacy Agents 단계를 따르세요. 사용 가능 여부는 구성원마다 다를 수 있으며, 이 문서가 사용 환경을 변경하지는 않습니다.
어느 경험에서든 여러 채팅이나 작업을 동시에 실행하고, 워크플로를 재사용하며, 검토한 작업을 팀과 공유할 수 있습니다. 런타임 서브에이전트는 별도의 제품 프로필로 만들어야 하는 것이 아니라 실행 도구입니다.
설정 차이점: My Okou는 Settings → Personal → My Okou의 개인 Instructions와 워크스페이스 Workflows를 사용합니다. 아래 단계 중 이름이 지정된 에이전트를 선택, 생성 또는 권한 부여하라고 하는 경우는 Legacy Agents에만 해당합니다. My Okou에서는 자신의 채팅을 사용하고, 표시되는 계정 및 명명된 권한 요청을 따르세요. 공유 Workflows는 자격 증명을 공유하지 않으며, Automations는 소유자의 컨텍스트와 액세스를 사용합니다.
사용자 지정 커넥터를 사용하면 조직 관리자가 기본 제공 카탈로그에 없는 HTTPS API 또는, 사용 설정된 경우 Streamable HTTP MCP 서버를 등록할 수 있습니다. 이 기능은 네트워크 경계와 인증 방법을 정의합니다. 에이전트를 위한 완전한 API 참조를 자동으로 생성하지는 않습니다.
누가 무엇을 구성하나요
- 조직 관리자는 커넥터 정의를 만들고, 편집하고, 삭제합니다.
- 구성원은 자신의 비밀 정보를 연결하거나 커넥터의 OAuth 흐름을 완료합니다.
- 권한 부여와 권한은 Okou가 연결을 통해 요청할 수 있는 이름이 지정된 작업을 제어합니다. Legacy Agents는 Agent별 권한 부여도 사용합니다.
정의는 조직 내에서 공유됩니다. 구성원 자격 증명은 구성원과 조직 범위에 한정되어 유지됩니다.
HTTP API 커넥터
- Connectors → Custom을 열고 New connector를 선택합니다.
- HTTP API를 선택하고 표시 이름을 입력합니다.
- HTTPS Prefixes를 하나 이상 추가합니다. 각 줄에 하나씩 입력하세요. 요청은 커넥터가 승인하기 전에 구성된 접두사와 일치해야 합니다.
- API에 인증이 필요한 경우 인증을 추가합니다:
- API authentication: 헤더 이름과
{{secret}}를 포함하는 헤더 템플릿을 입력합니다. 예:Authorization및Bearer {{secret}}. - OAuth 2.0: 승인 URL, 토큰 URL, 클라이언트 ID, 클라이언트 비밀, 범위, 토큰 엔드포인트 인증 방법을 입력합니다. 양식에 표시된 정확한 리디렉션 URL을 제공업체에 등록하세요.
- API authentication: 헤더 이름과
- 커넥터를 만듭니다. 그런 다음 필요한 각 구성원은 Connect를 선택하고 자신의 비밀 정보를 제공하거나 OAuth를 완료합니다.
- 필요한 이름이 지정된 권한을 검토하고 승인합니다. Legacy Agents에서는 의도한 Agent도 선택합니다.
기존 OAuth 정의나 해당 클라이언트 자격 증명을 변경하면 현재 OAuth 연결이 끊깁니다. 구성원은 변경 후 다시 연결해야 합니다.
MCP 커넥터
워크스페이스에서 MCP가 커넥터 유형으로 표시되면, HTTPS Streamable HTTP MCP 엔드포인트를 입력하고 같은 양식에서 API 또는 OAuth 인증을 구성하세요. 선택기에서 MCP가 제공되지 않으면 해당 워크스페이스에서 사용 설정되지 않은 것입니다.
에이전트에게 API 절차를 가르치기
사용자 지정 커넥터는 안전한 네트워크 액세스와 자격 증명 주입을 제공합니다. 생성 양식은 OpenAPI 문서를 업로드하거나 자동 검색하지 않습니다. 요청에서 에이전트에게 엔드포인트, 메서드, 매개변수, 예상 응답을 알려 주거나, 해당 절차를 파일로 첨부된 workflow에 캡처하세요.
알려진 엔드포인트에 대해 범위가 좁은 읽기 전용 요청으로 새 커넥터를 검증하세요. 많은 API가 의미 있는 루트 엔드포인트를 노출하지 않기 때문에 일반적인 Test connection 요청은 없습니다.
보안 경계
- HTTPS 접두사와 MCP 엔드포인트만 허용됩니다.
- 방화벽은 저장된 자격 증명을 일치하는 요청에만 주입합니다.
- 저장된 비밀 정보는 저장 시 암호화되며 환경 변수로 에이전트에 노출되지 않습니다.
- 키, 토큰 또는 클라이언트 비밀을 채팅 메시지, 워크플로 지침 또는 첨부 파일에 넣지 마세요.
- 워크플로에 필요한 최소한의 상위 범위만 가진 서비스 자격 증명을 사용하세요.
문제 해결
| 문제 | 확인 |
|---|---|
| New connector를 사용할 수 없음 | 커넥터 정의를 만들거나 편집할 수 있는 사람은 조직 관리자뿐입니다. |
| 에이전트가 커넥터를 볼 수 없음 | 현재 구성원에 대해 연결하고 필요한 권한을 검토하세요. Legacy Agents에서는 의도한 Agent도 권한 부여해야 합니다. |
| 요청이 API에 도달하기 전에 차단됨 | 요청 URL이 구성된 HTTPS 접두사 중 하나로 시작하는지 확인하세요. |
| API가 401 또는 403를 반환함 | 구성원의 자격 증명을 다시 연결하고 상위 키 또는 OAuth 범위를 확인하세요. |
| OAuth가 리디렉션 오류를 반환함 | 커넥터 양식에 표시된 정확한 리디렉션 URL을 등록하고 승인 및 토큰 URL을 확인하세요. |
| 에이전트가 잘못된 엔드포인트 또는 페이로드를 추측함 | 커넥터 이름에만 의존하지 말고 API 절차를 워크플로에 넣고 관련 참조를 첨부하세요. |
