arga-sdk v0.2.0+ package on a customer-owned Node.js host or container. The worker reads Braintrust directly, runs the same local projection, and uploads only selected evidence to Training. Your agent can use any language.
The braintrust package is not required for reading traces. Set BRAINTRUST_API_KEY to a project-appropriate read credential and ARGA_TRACE_KEY to an upload-only source key. Keep both in your secret manager; neither belongs in policy JSON, command arguments, source spans or logs. The Braintrust credential never goes to Arga.
Define the policy
Save a localtrace-policy.json:
goal_pointer selects a string from the root span using a JSON pointer. Use /input/task for {"input":{"task":"Resolve a refund..."}}, or /input when input is itself a string.
Canonical names such as stripe.charges.retrieve work without mappings. Mapped tool spans must carry provider-shaped arguments in input and the provider resource/page in output. Normalize custom envelopes such as output.result locally before calling projectTrace. Gmail tool output is the Gmail response data, not a Gaxios response envelope.
LLM, score and eval spans are ignored. Root output, arbitrary metadata and tool suggestions inside LLM output are excluded. Unknown executed tool spans create coverage gaps.
The JSON CLI policy selects only the goal and listed operating policy. Review those strings before export. Gmail text remains excluded. The CLI cannot run a custom text callback; use the programmatic worker below when your selected text needs one.
Start the worker
--region eu for EU Braintrust projects. The default is us; the Arga destination remains https://api.argalabs.com.
Without --watch, the CLI processes one bounded window. The watcher processes five-minute windows with two minutes of overlap and waits 30 seconds after catching up. Full child traces are read independently of the root discovery window. Root and tool metrics.start/metrics.end establish completed calls. Parallel reads are accepted; ambiguous mutation ordering blocks generation.
Use a custom local filter
filterTrainingText in your application and choose a private writable checkpoint path. The callback is synchronous and runs only on your host. If you normalize exported spans yourself, projectTrace(rows, options) creates a validated episode without making network calls; upload it through client.training.uploadEvidence(episode).
Progress and retries
syncOnce() returns uploaded, unchanged, pending, coverageGaps and caughtUp counters. Unfinished and malformed roots remain pending while healthy traces progress. Retry pending roots after fixing their source data or completing their spans.
A failed network read, invalid pagination or unacknowledged Arga upload stops the window without advancing its watermark. An acknowledged evidence digest is saved before moving on. Overlap replay suppresses unchanged uploads. Provider exception messages and source bodies are not included in worker diagnostics.
In --watch mode, transient failures retry with bounded backoff while retaining the checkpoint. Without --watch, a failure exits nonzero so your scheduler can retry. Signed HTTPS response-storage redirects are fetched without the Braintrust credential or query body, under the same read limits.
Reads are bounded to 2 MB and 1,000 rows per query. An oversized individual trace stays pending with a coverage gap while healthy roots progress. A root-discovery query hitting a limit stops the window; reduce its discovery window. At most 1,000 unresolved roots are retained. Resolve or normalize oversized traces on your host before backfilling them.
Checkpoints are written atomically with mode 0600 on POSIX hosts. They contain an alias key, watermark, pending root references and acknowledged digests, never raw spans or service credentials. Protect them as private files. A lock prevents concurrent workers from sharing one checkpoint. After a crashed worker, verify that it has stopped before removing its stale .lock file; locks are not automatically stolen.
Use a new checkpoint when changing project, source, initial timestamp, region, destination, policy revision, goal selection or operation map. Python and TypeScript checkpoints are separate formats. Renewing an upload key for the same owner/source can reuse the TypeScript checkpoint.
