콘텐츠로 이동

Agent 일상 사용 매뉴얼

이 문서는 Agent 서비스 설치를 완료한 사용자를 대상으로 합니다. 이 문서에서는 Agent의 상태를 확인하는 방법, 서비스 관리, 설정 변경, 로그 확인, 세션 버그 보고서 작성, 수동으로 업데이트 및 Agent를 제거하는 방법에 대해 설명합니다.

아래 명령어는 Linux/systemd 설치 방식에 적용됩니다. 서비스 관리, 구성 수정 및 제거 명령어를 실행하려면 일반적으로 호스트에서 sudo 권한이 필요합니다.

Agent 파일 찾기

기본 설치 후 Agent 관련 파일은 다음 위치에 있습니다:

유형 기본 위치
Agent 프로그램 /usr/local/bin/obs-agent
업데이터 프로그램 /usr/local/bin/obs-agent-updater
설정 파일 /etc/obs-agent/config.toml, agent.env는 오래된 업데이트 도구와의 호환성을 위해만 사용됩니다.
작업 디렉터리 /var/lib/obs-agent/work
프로파일 캐시 /var/lib/obs-agent/profile-cache
로그 디렉터리 /var/log/obs-agent
메인 로그 파일 /var/log/obs-agent/log
systemd 서비스 obs-agent.service

Skill와 MCP 업데이트

Agent은 기본 설정을 로드하고 세션을 준비한 후 Skills와 MCP 리소스를 하나씩 연결합니다. 종속성 준비 과정 중에도 채팅 기능은 계속 사용할 수 있습니다. 기존 세션에서 나중에 발생하는 요청들은 새로 준비된 기능을 사용할 수 있습니다.

의존성이 있는 Skills는 먼저 검사를 통과해야 합니다. 호스트 설치는 누락된 의존성이나 요구 사항을 충족하는 버전을 추가합니다. 컨테이너 이미지는 의존성을 제공해야 합니다. 업데이트에 실패한 리소스는 사용할 수 없으며 이전 버전으로 돌아가지 않습니다. 준비된 다른 리소스는 계속 사용할 수 있습니다. 기본 동기화 간격은 약 10분입니다. 실패하면 30초 후 재시도하고 성공하면 기본 간격으로 돌아갑니다. 더 짧은 간격을 설정하면 재시도에도 그 간격을 사용합니다.

Agent, Skill 또는 MCP 페이지에서 준비 결과를 확인하세요. 만약 로컬 리소스는 준비되어 있지만 상태가 변하지 않았다면, 보고 연결이 실패했을 가능성이 있습니다. 나중에 이루어지는 동기화에서 다시 확인됩니다. 세션을 다시 설치하거나 생성할 필요는 없습니다.

Agent 상태 확인

Agent가 실행 중인지 확인:

systemctl status obs-agent

서비스가 활성 상태인지만 확인:

systemctl is-active obs-agent

현재 설치된 Agent 버전 확인:

/usr/local/bin/obs-agent --version

Agent의 실행 사용자 확인:

systemctl show obs-agent -p User -p Group

기본적으로 Agent 서비스는 obs-agent 사용자로 실행되며, root로 지속 실행되지 않습니다. root는 주로 설치, 업그레이드, 제거와 같은 호스트 관리 작업에 사용됩니다.

Agent 시작, 중지 또는 재시작

Agent 시작:

sudo systemctl start obs-agent

Agent 중지:

sudo systemctl stop obs-agent

Agent 재시작:

sudo systemctl restart obs-agent

구성을 수정한 후 새 구성을 적용하려면 일반적으로 서비스 재시작이 필요합니다:

sudo systemctl restart obs-agent

Agent 로그 조회

최근 systemd 로그 조회:

journalctl -u obs-agent -n 100

최신 로그 실시간 조회:

journalctl -u obs-agent -f

Agent 메인 로그 파일 조회:

tail -n 100 /var/log/obs-agent/log

Agent가 시작되지 않는 경우 먼저 다음을 확인하는 것이 좋습니다:

systemctl status obs-agent
journalctl -u obs-agent -n 100

오프라인 상태에서 로컬 버그 보고서를 수집합니다.

Agent가 Beak에 연결할 수 없거나, 모델 호출이 실패하거나, 세션 도구가 실행되지 않는 경우, Agent 호스트에서 이 명령어를 직접 실행하세요:

obs-agent --bug-report

기본 깊이는 0입니다. 호스트, 프로세스, 설정, 로그, 발견 가능한 모든 세션 및 런타임 증거를 수집하며 상세 LLM 증거는 내보내지 않습니다. 보고서는 기본적으로 현재 디렉터리에 저장됩니다. --bug-report-output에는 디렉터리가 아닌 전체 ZIP 경로를 지정하세요. 대상 파일은 존재하지 않아야 하며 부모 디렉터리는 미리 있어야 합니다.

obs-agent --bug-report --bug-report-output /var/tmp/report.zip --depth 2

이 명령은 일반 Agent 런타임을 시작하거나 WebSocket에 연결하거나 모델을 호출하거나 승인을 요청하거나 파일을 업로드하지 않습니다. 표준 출력에는 JSON 한 줄만 표시됩니다. status는 completed 또는 partial이며 절대 경로, 크기, SHA-256 및 안정적인 오류 코드가 포함됩니다. 두 상태 모두 ZIP이 안전성 검증을 통과했음을 나타내며 종료 코드는 0입니다.

별도의 설정 파일을 사용하려면 --config /etc/obs-agent/config.toml을 추가하고 Agent 캐시와 로컬 진단 엔드포인트를 읽을 수 있는 계정으로 실행하세요. 깊이는 0..3입니다. 깊이 1은 호출 구조를 기록하고, 깊이 2는 기록된 공급자 요청, 응답 및 도구 증거의 원본을 추가합니다. 실행 중인 Agent가 이미 [diagnostics]에서 chat_depth = 2 이상을 사용해야 합니다. 이전 호출은 재구성할 수 없습니다. 깊이 3은 로컬 전용이며 UNREDACTED로 표시되고 마스킹되지 않은 내용을 유지합니다. 그대로 공유하지 마세요.

로컬 환경에서 보고서를 열려면 다음과 같이 하세요:

obscli bug-report view /var/tmp/report.zip

뷰어는 아카이브를 업로드하지 않고 기본 보고서, 기존의 상세 LLM 보고서 및 통합 보고서를 지원합니다.

실행 중인 Agent는 기본적으로 프로파일 캐시 아래 diagnostics/runtime.sock에 모드 0600의 로컬 진단 엔드포인트를 제공합니다. 힙 및 goroutine 프로파일, 30초 CPU 프로파일, 5초 런타임 트레이스, 명령줄, 메트릭 및 런타임 타임라인을 수집합니다. 이 엔드포인트는 Unix 소켓만 사용하며 TCP에서 수신하지 않습니다. 비활성화하려면 config.toml의 [runtime]에 local_diagnostics_enabled = false를 설정하세요.

컨테이너 내에서 다음 정보가 포함된 보고서를 생성하고 복사합니다:

docker exec obs-agent obs-agent --bug-report --bug-report-output /app/obs-agent-support.zip
docker cp obs-agent:/app/obs-agent-support.zip ./obs-agent-support.zip

고정된 ZIP 크기 제한은 없습니다. 수집은 출력 파일 시스템의 가용 공간을 동적으로 확보합니다. 복사 전에 size_bytes와 sha256을 확인하세요. 모든 깊이의 보고서에는 민감한 정보가 포함될 수 있습니다. config.toml(이전 설치에서는 agent.env)의 민감한 값 할당만 마스킹합니다. 다른 설정, 세션 콘텐츠, 로그 및 기록된 LLM 증거는 원본을 유지합니다. 깊이 3은 첫 호출부터의 완전한 원본 기록도 포함합니다. 파일은 0600 모드를 사용합니다. 통제된 지원 채널로만 전송하고 사용 후 삭제하세요.

세션 관련 버그 리포트를 수집합니다.

Agent가 예기치 않게 응답하지 않거나, 도구가 멈추거나, 연결이 불안정한 경우, 영향을 받는 세션의 Agent에게 진단 보고서를 수집하고 업로드하도록 요청할 수 있습니다(구성 파일에서 민감한 정보는 가려져 있습니다). Agent는 임시 다운로드 링크를 지정된 지원 이메일 주소로 직접 전송할 수 있으므로, 보고서를 수동으로 다운로드하고 전송할 필요가 없습니다.

사용 방법, 권한, 이메일 전송 및 실패 처리에 대한 자세한 내용은 세션에서 Agent 버그 보고서 수집 및 전송을 참조하세요.

온라인 수집은 현재 세션에 한해만 가능하며, chat_depth=0..2 형식을만 받습니다. 기본값은 0입니다. 세션 인증을 따르며, 보고서를 업로드합니다. chat_depth=3 형식은 거절됩니다.

Agent 구성 수정

Agent의 런타임 구성은 기본적으로 다음 위치에 저장됩니다:

/etc/obs-agent/config.toml

수정 전 백업을 권장합니다:

sudo cp -p /etc/obs-agent/config.toml /etc/obs-agent/config.toml.bak

구성 편집:

sudo vi /etc/obs-agent/config.toml

주요 구성 항목:

구성 항목 설명
beak.url 서비스 주소 Agent 연결
beak.api_key Agent 접속 자격증
beak.agent_id 현재의 Agent ID
llm.base_url LLM 서비스 주소
llm.api_key LLM 호출 자격증
runtime.working_dir Agent 도구 실행 작업 디렉터리
profile.cache_dir Agent 프로필, Skill, 그리고 스키마 캐싱 디렉터리
update.base_url Agent 릴리스 다운로드 주소
update.auto_enabled 지역 자동 업그레이드 스위치, 독립적인 업데이트 확인자가 확인함

Agent가 기업 프록시를 통해 Beak, LLM 또는 릴리스 서비스에 접근해야 하는 경우, Configure an obs-agent forward proxy에 설명된 대로 프록시 변수와 기업 CA를 구성하십시오.

llm.model는 선택적인 옵션이며, 기본적으로 auto 라우팅 방식으로 설정됩니다. 레거시 LLM_MODEL=default 방식은 여전히 auto로 로드됩니다. 고정된 모델 ID는 필요할 때만 설정해야 합니다. 자세한 내용은 Agent의 구성 방법]을 참조하십시오. 여기에는 그룹, 우선순위, 기본 설정, 비어 있는 값, 마이그레이션, 권한 등에 대한 정보가 포함됩니다.

수정 완료 후 서비스를 재시작합니다:

sudo obs-agent --config-tool agent-export --input /etc/obs-agent/config.toml --output /etc/obs-agent/agent.env
sudo systemctl restart obs-agent

구성 오류로 인해 서비스가 시작되지 않는 경우 백업에서 복원할 수 있습니다:

sudo cp -p /etc/obs-agent/config.toml.bak /etc/obs-agent/config.toml
sudo obs-agent --config-tool agent-export --input /etc/obs-agent/config.toml --output /etc/obs-agent/agent.env
sudo systemctl restart obs-agent
주의

config.toml 파일과 그에 생성된 호환성 파일인 agent.env에는 API 키, 토큰, 접근 주소와 같은 민감한 정보가 포함될 수 있습니다. 완전한 구성 파일을 공개된 채팅방, 티켓, 코드 저장소 또는 스크린샷에 전송하지 마세요.

개인용 Owl 키 모드

Agent는 기본적으로 설치 시의 Owl 자격 증명을 사용합니다. 개인 Owl 키 모드에서는 일반 세션이 세션 생성자의 개인 Open API 키를 사용합니다. 예약 작업과 사용자 Webhook은 설정 생성자의 키를 사용합니다. 후속 질문을 보내도 발신자의 키로 전환하지 않습니다. IM과 여기에서 파생된 위임은 설치 자격 증명을 유지합니다. 개인 키가 없거나 비활성화되거나 삭제되면 실행을 거부하며 설치 자격 증명으로 대체하지 않습니다.

먼저, Beak, Backend/Connector, Owl, 그리고 Agent 구성 요소들을 업그레이드해야 합니다. 제작자의 개인 키가 동기화되었는지 확인해야 합니다. Owl는 runtime-profile/v1를 지원해야 하며, 설치 과정에서는 이 기능의 가용성을 확인합니다. 업그레이드 설정을 해당 프론트엔드에 저장한 후, Agent를 다시 설치하여 AGENT_OWL_USER_TOKEN_ENABLED=true를 적용합니다. 기본값은 false입니다. 일반적인 업그레이드에서는 로컬 모드가 유지됩니다. 설정을 저장하거나 재시작해도 새로운 설치 모드로 전환되지 않습니다.

각 ID는 별도의 Owl 및 Profile 자격 증명과 쿼리 결과 디렉터리를 사용합니다. 기본 디렉터리에 저장된 이전 결과는 복사되지 않습니다. 키의 교체 또는 취소는 기존 키를 사용하는 실행 중이거나 대기 중인 작업을 취소합니다. 필요할 때 새로운 요청을 보내야 합니다. 접근 거부 사항에 대해서는 대상 워크스페이스의 창작자의 역할과 쿼리 권한을 확인해야 합니다. 거부를 우회하기 위해 다른 자격 증명을 사용하지 마세요. Profile 격리 기능은 동일한 시스템 사용자 하에서 임의의 스크립트에 대한 운영 체제 샌드박스를 제공하지 않습니다.

배포 전에 백엔드 출력 데이터베이스의 변경 사항을 검토하세요. Beak를 이 모드가 비활성화된 상태로 배포한 후, 새로운 기능이 포함된 Owl과 전체 Agent 배포 패키지를 사용하여 백엔드/커넥터를 배포합니다. 설정을 저장하고 다시 설치하여 이 기능을 활성화합니다. 롤백하기 전에 해당 모드를 비활성화하고 다시 설치합니다. 자격 증명의 수정 워터마크와 기존의 암호화 설정을 보존하여, 오래된 자격 증명이 새로운 상태를 덮어쓰지 못하도록 합니다.

Agent 수동 업데이트 또는 롤백

v0.16.0에서, 새로운 유지 관리 프로토콜을 지원하는 호스트는 기존 작업을 완료한 후에 오래된 프로세스를 중단합니다. 완전한 배포 패키지를 설치하고, 시작 및 실행 가능한 버전의 유효성을 검증합니다. 세션은 유지 관리, 성공, 실패, 복구 결과를 나타냅니다. 유지 관리 중에 제출된 메시지는 Beak에 남아 있으며, 재 연결 후 자동으로 다시 시작됩니다. 사용 가능한 종속 항목은 계속 설치되어 있으며, 누락된 종속 항목은 추가됩니다. 다운로드 또는 유효성 검증 실패는 기존의 복구 흐름을 통해 이전의 배포 패키지를 복원합니다.

내부 버전 통합 루프, obscli agent pin-version, 그리고 POST /api/v1/agents/{id}/version:pin는 제거되었습니다. AGENT_UPDATE_ENABLED와 AGENT_UPDATE_CHECK_INTERVAL_SECONDS는 더 이상 사용되지 않습니다. 로컬 systemd 타이머는 update.auto_enabled에 의해 제어되는 자동 업그레이드를 트리거합니다. 기존의 업데이트 방법은 여전히 지원됩니다. --target-version은 한 번의 작업을 위한 대상을 선택하며, 영구적인 버전 핀을 생성하지 않습니다.

Agent는 로컬 업데이터를 통해 버전을 전환할 수 있습니다.

이전 업데이터는 수동 교체 없이 기존 업그레이드 명령을 사용할 수 있습니다. 유휴 보호를 지원하는 Agents는 진행 중인 작업이 끝날 때까지 기다립니다. 업그레이드 중 Beak이 수락한 새 대화는 재연결 후 자동으로 다시 시도합니다. 유휴 프로토콜이 없는 이전 Agents는 첫 전환 중 바로 재시작하므로 진행 중인 대화가 중단될 수 있습니다. 이후 업그레이드는 유휴 보호를 사용합니다.

만약 관리된 업그레이드가 실패하면, 설치 프로그램은 이전의 바이너리, 구성, 서비스를 복원하려고 시도하며, 동시에 오류 진단 정보도 유지됩니다. 동일한 대상에 대한 재시도는 기존의 백오프 정책에 따라 이루어집니다. 새로운 대상은 이전 대상의 지연 시간을 상속받지 않습니다.

릴리스 소스의 최신 버전으로 업데이트:

sudo /usr/local/bin/obs-agent-updater

Agent가 이미 최신 버전이라도, 이 명령어는 Browser와 같은 구성 요소들의 설치를 다시 시도하기 위한 전체 업그레이드를 수행합니다. 버전이 변하지 않았다면, 배경 타이머 검사는 이러한 구성 요소들을 다시 설치하지 않습니다.

특정 버전 설치:

sudo /usr/local/bin/obs-agent-updater --target-version v0.2.0

롤백에도 같은 명령어를 사용합니다. 예를 들어, v0.1.9로 되돌리려면 다음과 같이 명령합니다:

sudo /usr/local/bin/obs-agent-updater --target-version v0.1.9

자동 업데이트 타이머 상태 확인:

systemctl status obs-agent-update-check.timer
systemctl list-timers obs-agent-update-check.timer

업데이트가 실패하면 다음을 우선 확인하십시오:

  • update.base_url를 /etc/obs-agent/config.toml로 확인하고, 생성된 호환성 파일이 동기화되었는지 확인하세요.
  • 릴리스 주소에 install.sh, 대상 버전 설치 패키지 및 검증 파일이 존재하는지;
  • journalctl -u obs-agent-update-check.service -n 100에 다운로드, 검증 또는 스케줄링 오류가 있는지;
  • journalctl -u obs-agent -n 100에 시작 또는 재시작 오류가 있는지.

/etc/obs-agent/config.toml의 [proxy]에서 프록시를 설정한 다음, 이전 업데이터를 위해 agent.env를 내보내세요. 자동 업데이트에 프록시 계속 사용을 참조하세요.

Agent 제거

제거 스크립트는 기본적으로 제거 계획만 표시하며 어떤 내용도 삭제하지 않습니다:

curl -fsSL https://static.guance.com/obs-agent/uninstall.sh | sudo bash

올바른지 확인한 후 --yes로 전체 제거를 실행합니다:

curl -fsSL https://static.guance.com/obs-agent/uninstall.sh | sudo bash -s -- --yes

제거 시 다음 고정 객체가 삭제됩니다:

  • /usr/local/bin/obs-agent
  • /usr/local/bin/obs-agent-updater
  • /usr/local/bin/obs-agent-update-check
  • /etc/obs-agent
  • /var/lib/obs-agent
  • /var/log/obs-agent
  • obs-agent.service
  • obs-agent-update-check.service
  • obs-agent-update-check.timer
  • /etc/sudoers.d/obs-agent
  • obs-agent 사용자 및 사용자 그룹

제거 시 skill-dep.sh가 설치하거나 확인한 Skill 런타임 의존성은 삭제되지 않습니다. 여기에는 시스템 명령어, 언어 런타임, Python/Node 패키지, 폰트 또는 기타 시스템 패키지가 포함됩니다. 이러한 의존성은 호스트에 원래 존재하던 공유 구성 요소이거나 다른 서비스에서 재사용될 수 있으므로 Agent 제거 프로세스에서 삭제할 수 없습니다.

일반적인 점검 사항

페이지에서 Agent가 오프라인으로 표시되는 경우

다음 순서로 확인하는 것이 좋습니다:

  1. 호스트 서비스가 실행 중인지: systemctl status obs-agent
  2. 호스트 네트워크에서 서비스 주소에 접근할 수 있는지;
  3. /etc/obs-agent/config.toml의 beak.url, beak.api_key, beak.agent_id가 올바른지 확인합니다.
  4. 최근 로그에 인증 실패, 네트워크 연결 실패 또는 DNS 확인 실패가 있는지.

Agent 구성 변경이 적용되지 않는 경우

서비스가 재시작되었는지 확인합니다:

sudo systemctl restart obs-agent

그런 다음 로그를 확인하여 새 프로세스가 시작되었는지 확인합니다:

journalctl -u obs-agent -n 50

업데이트 후 Agent 버전이 변경되지 않은 경우

먼저 현재 버전을 확인합니다:

/usr/local/bin/obs-agent --version

그런 다음 업데이트 로그를 확인합니다:

journalctl -u obs-agent-update-check.service -n 100
journalctl -u obs-agent -n 100

특정 버전 업데이트인 경우, 명령어의 버전 번호가 릴리스 소스의 버전 번호와 일치하는지 확인합니다.

문서 평가

이 페이지가 도움이 되었나요?