Tobeware.AgentOps.Bridge 0.1.0-preview.1

Tobeware AgentOps Bridge

AgentOps Bridge for .NET — captures Agent (LLM/Tool) execution into hash-chained Step events with HITL, ScopeGuard, Privacy redaction, and graceful shutdown. Conforms to agentops-spec contracts.

설치

dotnet add package Tobeware.AgentOps.Bridge --prerelease

현재 버전 0.1.0-preview.1 (alpha) — wire format 안정 (agentops-spec contracts/jsonschema 정합), API 표면은 stable 1.0.0 까지 변경 가능. semver minor (preview.N → preview.N+1) 단위로 변경 사항 표시.

사용 예시 (사이드카 모드)

using Snapper.AgentBridge.Adapters;
using Snapper.AgentBridge.Hosting;
using Snapper.AgentBridge.Interceptors;
using Snapper.AgentBridge.Models;
using Snapper.AgentBridge.Services;
using Snapper.AgentBridge.Storage;
using Snapper.AgentBridge.Transport;

// 1) Execution + Tree builder
var execution = new AgentExecution
{
    ExecutionId = CorrelationIds.NewId(),
    AgentId = "my-agent",
    SessionId = CorrelationIds.NewId(),
    StartedAt = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
    Status = ExecutionStatus.RUNNING,
};
var hashChain = new HashChainService();
var treeBuilder = new AgentExecutionTreeBuilder(hashChain, execution);

// 2) LLM 인터셉터 + Mock adapter
var registry = new InterceptorRegistry()
    .Register(new OpenAiInterceptor())
    .Register(new AnthropicInterceptor())
    .Register(new GeminiInterceptor());
var mockAdapter = new MockHttpAdapter(registry, treeBuilder);

// 3) Transport + Disk queue + Hosting
var batch = new BatchAccumulator(maxSteps: 200, flushInterval: TimeSpan.FromSeconds(5));
var transport = new RestAgentLogTransport(new Uri("https://wk.example.com/api/"));
var queue = new DiskBackedLocalQueue();
var hosted = new AgentBridgeHostedService(batch, transport, queue,
    payloadBuilder: steps => new ExecutionLogPayload { Execution = execution, Steps = steps });

await hosted.StartAsync(CancellationToken.None);
// ... agent 실행 ...
await hosted.StopAsync(CancellationToken.None);

핵심 기능

• Hash chain (SHA-256 canonical JSON) — SDK Python _hash.py 와 binary diff 0 보장. 6 키 도메인 (input_data / output_data / started_at / ended_at / node_type / hash_prev)
• LLM 인터셉터 4종 — OpenAI / Anthropic (G6 thinking block) / Gemini (Vertex region 호환) / Internal (3 compat 모드)
• Tool 인터셉터 — HttpClient DelegatingHandler + LLM provider host 자동 skip
• HITL 게이트 — IHitlGateClient 추상화 + HitlRequestRouter correlationId 매칭 + PauseGate + KillSwitchManager (5초 deadline 강제 종료)
• ScopeGuard — 6 ViolationType (TOOL/DOMAIN/COST/TIME/DATA/TOKEN) + 라이선스 한도 (max_steps_per_execution / max_tokens_per_execution) + Hot reload
• Privacy redaction — keys (case-insensitive) + Regex patterns + custom Func + JSON tree 재귀
• Transport — HttpClient + 5단계 backoff (1s/2s/4s/8s/30s) + X-Idempotency-Key 보존 + BatchAccumulator (200건 또는 5초 마감)
• DiskBackedLocalQueue — %LocalAppData%/SnapperStudio/AgentBridge/queue/ FIFO + dead-letter + 손상 파일 자동 격리
• NTP 보정 — Cristian 알고리즘 (SDK Python _ntp.py 동등) + drift > 1s 경고
• Graceful shutdown — IAgentBridgeHostedService + GracefulShutdownCoordinator (5초 grace + 강제 종료 콜백)

권위 spec

• agentops-spec/teams/snapper/ — Phase 정의 / 우선순위 / 스프린트 계획
• agentops-spec/contracts/jsonschema/step.schema.json — Step wire format
• agentops-spec/contracts/05-rest-api-contract.md — REST 송신
• agentops-spec/contracts/06-websocket-protocol.md — WS 게이트
• agentops-spec/contracts/08-agentops-sdk-spec.md — SDK 동등성

차단 잔존 (preview → stable)

본 라이브러리의 현재 alpha (0.1.0-preview.1) 는 다음 항목이 추상화 + Mock 으로 구현됨. stable (1.0.0) 시점에 실 wire-up:

상세 차단 트래킹: agentops-spec/teams/snapper/STATUS.md § 5

단위 테스트

184/184 PASS (~850ms, Load 3건 별도 [Trait Load] gate). E2E 시나리오 ✅: 5xx fallback / 4xx dead-letter / HitlRequest 승인-거부 / KillSwitch token cancel / 50 동시 add SIGTERM grace.

사이드카 (Snapper.AgentBridgeRunner.exe)

본 라이브러리의 콘솔 사이드카는 별도 ship — 본 NuGet 에 포함되지 않음. Snapper Studio Pro 인스톨러 동봉 또는 별도 zip 배포. 자세히는 docs/operator-guide/.

사용자 정의 사이드카: 본 라이브러리의 IAgentBridgeHostedService + GracefulShutdownCoordinator 를 직접 호스트.

라이선스

MIT — 본 NuGet 패키지 (Tobeware.AgentOps.Bridge) 만. Snapper Studio Pro desktop 앱 (Snapper.UI / Snapper.Core / Snapper.Infrastructure 등) 은 별도 commercial license.

사용자 가이드

상세 사용 가이드 + 트러블슈팅: docs/nuget-consumer-guide.md.

빌드 (개발자)

dotnet build Snapper.AgentBridge/Snapper.AgentBridge.csproj -c Release
dotnet pack Snapper.AgentBridge/Snapper.AgentBridge.csproj -c Release -o ./out --include-symbols --include-source

전체 솔루션 (Snapper_Studio_2025.sln) 빌드 시 자동 포함. WPF/Windows 종속 없음.