콘텐츠로 이동

Agent의 설정 구성

호스트 설치에는 /etc/obs-agent/config.toml를 사용합니다. 설치 프로그램이 이 파일을 생성합니다. 수정하기 전에 이 파일을 백업하고, 그 후에 파일의 유효성을 확인한 다음 서비스를 다시 시작해야 합니다. 이 파일에는 자격 증명이 포함되어 있습니다. 소유권은 root:obs-agent이고, 권한은 0640입니다. 전체 파일을 공개된 문제에 첨부하지 마세요.

설정 편집

config_version = 1

[beak]
url = "https://beak.example.com"
agent_id = "replace-with-agent-id"
api_key = "replace-with-agent-api-key"

[llm]
# model = "auto"
# request_timeout = "5m"
# max_tokens = 0

[runtime]
working_dir = "/var/lib/obs-agent/work"
# http_allowed_domains = ["example.com", "api.example.com"]

[profile]
cache_dir = "/var/lib/obs-agent/profile-cache"

[logging]
level = "info"
# format = "text"

[update]
base_url = "https://releases.example.com/obs-agent"
# auto_enabled = true

[tools.browser]
# enabled = true

[tools.web_search]
# enabled = true

설치 프로그램은 필수 설정과 명시적으로 지정된 설정을 기록합니다. 설정하지 않은 필드는 알려진 환경 변수 또는 내장 기본값을 사용합니다. 예제 필드를 명시적으로 설정하려면 주석을 해제하세요. update.socket_path가 설정되지 않으면 Agent는 update.state_path와 같은 디렉터리의 update.sock을 사용합니다. 임시 경로를 지정할 필요는 없습니다.

실행 시간 및 도구 사용 시간 제한

설정 기본 설정 범위/규모
runtime.max_run_duration "2h" 각 실행의 소프트 시간 한도입니다. 세션 자체의 수명이 아닙니다. "0s"로 비활성화합니다.
runtime.subagent.max_runtime "8h" 하위 에이전트 감독관의 예산도, 부모 작업의 남은 시간에 의해 제한됩니다.
runtime.wait_for_max_duration "8h" 하나의 wait_for 요청도, 부모 작업의 남은 시간에 의해 제한됩니다.

8 시간 제한은 2 실행 시간 제한을 연장하지 않습니다. 하위 에이전트는 부모의 취소 기능을 상속받습니다. 부모의 남은 시간을 초과하는 wait_for 요청은 거부됩니다. 더 긴 작업을 실행하려면 runtime.max_run_duration를 명시적으로 설정하고 적절한 하위 에이전트 및 대기 시간 제한을 유지해야 합니다.

소프트 예산이 만료될 때, Agent은 스트리밍 및 압축 요청을 포함한 활성 모델 요청을 기다립니다. 유효한 최종 결과를 유지합니다. 추가적인 작업이 필요한 경우, 새로운 도구를 시작하지 않고 최대 하나의 요약 결과만을 요청합니다. 실패한 요약 결과는 체크포인트로 반환됩니다. 실제 소요 시간은 예산을 초과할 수 있습니다. 만약 컨텍스트가 요약 결과를 표현할 수 없거나, 민감한 구성 정보가 구조화된 출력으로만 표시될 경우, Agent은 직접적으로 체크포인트를 반환합니다.

시간 제한이 활성화된 경우, 재시도를 포함한 모든 모델 요청은 임시 user 메시지로 끝나며, 이 메시지에는 총 소요 시간과 남은 시간이 표시됩니다. 이 메시지는 세션 기록에 저장되지 않습니다. 이 메시지는 도구 수, 모델 호출 수, 토큰 사용량을 제외합니다. 호출 및 토큰 총량은 내부 진단 정보로 남아 있으며, 더 이상 실행을 중단시키지 않습니다. 시간 제한이 비활성화된 경우, 예산 관련 메시지는 추가되지 않습니다.

연결된 obscli 세션에서는 다음을 사용합니다:

명령 행동/주의
/max-run-duration 저장된 설정 표시, Agent 애플리케이션 상태, 그리고 경과된/남은 시간을 확인할 수 있습니다.
/max-run-duration 10m 이 세션에서 각 세션의 실행 시간을 10분으로 제한합니다.
/max-run-duration +5m 5분을 추가합니다. 상속된 기본 설정에는 일관된 기본값을 가진 온라인 Agent이 필요합니다.
/max-run-duration 0 세션의 시간 제한을 비활성화합니다.
/max-run-duration reset 각 Agent의 기본 설정을 복원합니다.

설정은 유지되며 현재 실행과 이후 실행에 적용됩니다. 실행마다 새 타이머를 시작합니다. 이미 요약 단계에 들어간 실행은 조사를 재개하지 않습니다. 실행 중인 하위 작업은 부모의 제한 변경을 따르지만 독립된 제한이 더 짧으면 유지합니다. API는 GET/PUT /api/v1/sessions/:id/max-run-duration이며 PUT 본문으로 {"duration":"+5m"} 등을 사용할 수 있습니다. 쓰기 권한이 있는 세션 참여자만 변경할 수 있습니다. applied는 연결된 Agent가 적용을 확인했다는 뜻입니다. pending, offline, unsupported는 활성화되었다는 뜻이 아닙니다.

승인 대기 시간도 실행 시간에 포함됩니다. 기한에 도달하면 대기가 끝나고 실행하지 않은 도구는 실행되지 않습니다. 늦은 승인으로 중지된 작업을 다시 시작할 수 없습니다. 실행 제한을 바꾸면 대기 기한을 다시 계산합니다. Browser 제어 승인은 독립적으로 30분 후 만료됩니다. 실행 시간을 늘려도 승인 유효 기간은 연장되지 않습니다. 수동 취소, 모델 요청 시간 초과 및 도구 시간 초과는 서로 독립적입니다.

예를 들어, 기존의 [runtime] 섹션에 max_run_duration = "4h"를 설정하여 4시간 동안 사용할 수 있도록 합니다. 그 후 아래와 같이 유효성 검사 및 재시작을 수행합니다. 호스트와 컨테이너의 기본 설정은 2시간입니다. 컨테이너는 AGENT_MAX_RUN_DURATION=4h를 설정할 수 있습니다.

불리언에는 true 또는 false, 숫자에는 따옴표 없는 숫자, 목록에는 배열, 기간에는 "5m" 같은 단위가 있는 값을 사용합니다. 이전 max_llm_calls와 max_run_tokens를 포함하여 알 수 없는 필드와 테이블은 무시합니다. 알려진 필드는 유효한 유형과 값이 필요합니다. 잘못된 구문과 지원하지 않는 설정 버전은 거부합니다. 이전 환경 변수 제한과 AGENT_MAX_TOOL_CALL_ITERATIONS 별칭은 더 이상 읽지 않습니다.

구성 우선순서

호스트 설치의 우선순위는 TOML, 알려진 환경 변수, 내장 기본값 순서입니다. 필드가 있으면 값이 "", false, 0이어도 환경 변수보다 우선합니다. 잘못된 값은 오류를 발생시키며 다른 값으로 대체하지 않습니다.

기본 파일은 /etc/obs-agent/config.toml입니다. 파일이 없으면 Agent는 기존에 배포된 agent.env 형식을 사용합니다. 두 파일을 병합하지 않습니다. 업그레이드는 이전 파일을 마이그레이션하고 백업을 보관합니다. 기존 TOML 설정과 사용자 주석은 유지됩니다.

TOML 호환성이 있는 Agent의 경우, Linux 설치 프로그램은 --config /etc/obs-agent/config.toml를 명시적으로 사용하는 서비스를 생성합니다. 업그레이드 전 준비 과정에서도 동일한 파일이 사용됩니다. 주요 서비스는 호환성 관련 agent.env을 로드하지 않습니다; 구형 업데이트 도구는 여전히 이를 사용합니다.

필드를 삭제하거나 코멘트로 처리하여 환경 변수나 기본값이 해당 값을 제공할 수 있도록 합니다. config_version = 1은 구성 스키마 버전이며, Agent 릴리스 버전은 아닙니다. 지원되지 않는 버전은 거절됩니다.

Agent 구성 도구는 허용된 설정을 변경할 수 있으며, 주석, 빈 줄 및 기타 필드는 그대로 유지됩니다. 동시에 수정하면 오래된 변경 사항이 무효화됩니다. 다시 시도하기 전에 파일을 다시 읽어보세요.

검증, 전송, 재시작

sudo cp -p /etc/obs-agent/config.toml /etc/obs-agent/config.toml.bak
sudo vi /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
sudo systemctl status obs-agent

유효성 검증에 실패할 경우 재시작하지 마세요. 출력 명령어는 오래된 업데이트 프로그램이 읽을 수 있는 파일에 알려진 설정을만 기록합니다. 생성된 agent.env 설정 파일을 수정하지 마세요. Agent 설정 도구가 이 파일을 동기화합니다.

다른 파일을 선택하려면 obs-agent --config /path/to/config.toml를 사용하세요. 이 옵션을 기존의 --env-file 옵션과 함께 사용하지 마세요.

만약 서비스가 시작되지 않으면, 백업을 복원하고 호환성 파일을 다시 생성해야 합니다.

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

구형 구성에서 업그레이드하기

TOML 지원 버전으로 처음 호스트를 업그레이드할 때는 전환 전에 agent.env를 변환하고 검증합니다. 수동 변환이나 필드 매핑은 필요하지 않습니다. 기본값과 같은 값을 포함하여 유효한 알려진 설정을 유지합니다. 이전 형식의 빈 값은 기존과 같이 미설정으로 처리합니다.

알 수 없는 변수들은 TOML에 포함되지 않습니다. 설치 프로그램은 이러한 변수들의 이름만을 표시하며, 원본 파일은 백업으로 저장됩니다. 이러한 변수들의 원래 목적을 확인해 주세요. 일반적인 환경 변수 그룹은 존재하지 않습니다.

구형 업데이너들은 기존의 명령어를 그대로 사용할 수 있으며, 새로운 인수나 추가적인 자가 업데이트가 필요하지 않습니다. 여전히 ‘유휴 보호 기능’이 유지됩니다. 마이그레이션이나 시작 과정에서 문제가 발생할 경우, 업그레이드는 기존의 프로그램, 구성, 서비스를 복원합니다. ‘유휴 프로토콜’이 없는 확실한 역사적 실행 환경에서는, 첫 번째 전환 과정 중에 작업이 중단될 수 있습니다. 업그레이드된 실행 환경은 ‘유휴 보호 기능’을 사용합니다.

Agent 컨테이너를 설정합니다.

컨테이너는 환경 변수만 사용합니다. config.toml을 읽거나 생성하지 않으며 Agent 파일 인수 --config와 --env-file도 지원하지 않습니다. Docker, Compose 또는 Kubernetes 설치 페이지의 환경 설정을 사용하세요.

Docker의 --env-file 인수는 계속 사용할 수 있습니다. Docker가 변수를 컨테이너에 주입하며 Agent는 해당 파일을 읽지 않습니다. 컨테이너 설치 가이드를 참조하세요.

업그레이드 호환성

LocalProvider는 더 이상 agent_max_llm_calls 또는 agent_max_tool_call_iterations을 읽거나 전송하지 않습니다.

발표된 설치 프로토콜에서는 여전히 이전의 Agents 및 이전 버전의 설치 프로그램에 사용되던 기존의 제한 필드를 수용하고 전달합니다. 새로운 Agents 버전에서는 이러한 필드을 읽거나 강제로 처리하지 않습니다.

BREAKING CHANGE: 새 Agents는 누적 호출 수나 토큰 제한을 더 이상 적용하지 않습니다. 배포 전에 비용 관리가 이 필드에 의존하지 않는지 확인하세요. 먼저 Beak을 업그레이드하고 기존 설치 또는 자동 업그레이드 절차로 Agents를 업데이트하세요. 이전 Agents는 연결과 채팅이 가능하지만 세션 제한을 적용하지 않습니다. 선택적 기능 session_run_duration=v1이 지원 여부를 나타냅니다. Agent를 롤백하면 이전 제한이 복원되고 세션별 재정의는 무시됩니다. 나중의 업그레이드를 위해 세션 설정을 유지하세요. Beak을 롤백할 때 NULL을 허용하는 run_duration 열을 삭제하지 마세요. 설치 프로그램과 업데이터의 호출 계약은 변경되지 않습니다.

문서 평가

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