GET STARTED

From your first agent run
to signed evidence.

Instrument your agent, inspect its recorded steps, and apply policy before guarded tool calls execute.

Connect your first agent

1. Sign in to your workspace. Pilot signup currently requires an invitation code; contact info@traceryx.com for access.
2. Open Connect agents, give your API key a label, and create it. Copy the token into your deployment secret store—it is shown only once.
3. Set the following environment variables in the process running your agent. This is configuration in dotenv format; the SDK does not automatically load a .env file.

TRACERYX_API_KEY=your_workspace_key
TRACERYX_ENDPOINT=https://app.traceryx.com

Use a server-side runtime. Never put the API key in browser code, URLs, source control, or telemetry payloads.

Run one of the examples below, then open Agent runs. The dashboard refreshes every 15 seconds. Select your agent, inspect its timeline, and choose Verify evidence.

Your account and workspace

The signup screen explains the current access requirements. When email signup is enabled, enter your name, workspace name and email, then use the verification email to create your password. Verification links expire after 24 hours and work once. You can request a fresh link from the sign-in screen.

Forgot your password? Request a reset email. Reset links expire after 30 minutes, work once, and sign out existing browser sessions after the password changes. Existing API keys remain active; revoke any compromised key separately in Connect agents.

Never share verification links, reset links, passwords or API keys. If account email is unavailable, contact info@traceryx.com.

Explore before connecting an agent

Open Sample runs in your workspace to walk through an allowed tool call, redaction, and a blocked action. These are fictional examples for learning the interface. They do not contain customer activity, generate signed evidence, or count toward setup progress.

In Connect agents, create a workspace key, configure the SDK, and run the example. Setup confirms a real SDK run has arrived. You can return to the guide at any time.

PYTHON 3.9+

Trace a Python agent

Install the published SDK, save the example as agent.py, and run it with your environment variables configured.

pip install traceryx==0.1.0
python agent.py

import os
from traceryx import TracerYX

tracer = TracerYX(
    api_key=os.environ["TRACERYX_API_KEY"],
    endpoint=os.environ["TRACERYX_ENDPOINT"],
    agent_name="my-first-agent",
)
try:
    run = tracer.run(input={"task": "check an order"})
    with run:
        with run.tool("lookup-order", input={"orderId": "DEMO-42"}) as tool:
            tool.set_output({"status": "ready"})
        run.set_output({"status": "complete"})
    packet = run.seal()
    if packet is None:
        raise RuntimeError("Evidence was not sealed; inspect delivery counters.")
finally:
    tracer.shutdown()

The context closes the run; run.seal() flushes its events and requests a signed packet. This example records a local fixture. Replace the fixture with your own tool implementation.

TYPESCRIPT · NODE.JS

Trace a TypeScript agent

Save the example as agent.ts. The tsx development runner executes TypeScript without requiring a project-wide module-format change.

npm install @traceryx/sdk@0.1.0
npm install --save-dev tsx
npx tsx agent.ts

import { TracerYX } from "@traceryx/sdk";

async function main() {
  const tracer = await TracerYX.init({
    apiKey: process.env.TRACERYX_API_KEY!,
    endpoint: process.env.TRACERYX_ENDPOINT!,
    agent: { name: "my-first-agent", version: "1.0.0" },
  });
  try {
    const { run } = await tracer.run("check-order", async (run) => {
      return run.tool("lookup-order", async () => ({ status: "ready" }));
    });
    const packet = await tracer.seal(run.id);
    if (!packet) throw new Error("Evidence was not sealed.");
  } finally {
    await tracer.shutdown();
  }
}
main().catch(() => {
  process.stderr.write("Agent run or evidence delivery failed.\n");
  process.exitCode = 1;
});

Tracing and guarding are separate

A traced tool records activity. To apply policy before a callback executes, explicitly wrap that callback with a guard. Instrument the boundary where data leaves your application.

from traceryx import PolicyStopped, PolicyUnavailable

def send_update(payload):
    # Replace this local preview with your real integration.
    return {"preview": payload}

try:
    result = tracer.guard(
        send_update,
        {"email": "customer@example.com", "summary": "Ready for handoff"},
        tool_name="sendResolution",
        destination="support.traceryx.local",
    )
except PolicyStopped:
    # The policy blocked execution; do not call the tool again unguarded.
    result = {"status": "blocked"}
except PolicyUnavailable:
    # Fresh authenticated policy is unavailable. Pause or retry safely.
    result = {"status": "policy-unavailable"}

The example destination is a fixture identifier, not an external service to contact. Configure your actual destination in the workspace policy. The guard checks the destination you supply; it does not independently intercept or inspect every network request.

Understand policy outcomes

Shadow mode records what policy would decide and passes the original payload to the callback. It does not enforce redaction or blocking.

Manage destination allowlists, PII/payment handling, action ceilings, and keyword screens in Policy. Secret egress is blocked by policy in this build. The SDK caches authenticated policy for up to 60 seconds, so updates are not necessarily immediate.

Use the policy playground with synthetic input to understand a decision before changing a production policy. Keyword screens are not a complete prompt-injection defense.

What stays local—and what is sent

SDK telemetry defaults to privacy="redacted". Supported patterns are redacted in the agent process before telemetry is sent. hash_only captures input/output fingerprints; full explicitly permits input/output capture and should be chosen deliberately.

Detection is pattern-based and can miss sensitive data. Test your own formats with synthetic fixtures. We have not established comprehensive PHI detection.

The current integration requires SDK instrumentation. It is not an automatically deployed sidecar or a zero-code network interceptor. You host your agents; the current hosted console runs on DigitalOcean.

Workspace API keys authenticate access to that workspace. Revoke a key in Connect agents when retiring or rotating it. Create and deploy its replacement before revocation to avoid interruption.

Verify the recorded packet

1. Select a run and choose Verify evidence.
2. Open Signed evidence for packet downloads, the attestation report, and OpenTelemetry exports.
3. Use the offline verifier with the packet and the matching public key when verifying outside the app.

Evidence uses Ed25519 signatures and canonical hashes. Verification checks integrity and the recorded chain. SDK telemetry remains client-reported: a valid signature does not establish that every action was instrumented or that the recorded activity is true.

Hosted evidence endpoints require authorization. Share exports only with intended recipients; they may contain recorded telemetry and identifiers. Control mappings are supporting evidence, not a compliance certification.

Troubleshooting

No runs appear

Check the endpoint and workspace key. Confirm the run context closed, flush or seal the run, inspect SDK delivery counters, and refresh Agent runs.

401: authentication failed

Check for a missing, incorrect, or revoked API key. SDK telemetry can disable after a 401; correct the credential and restart the client.

429: rate limited

Respect Retry-After and reduce ingestion concurrency. The current SDK events and policy routes each allow 240 requests per minute per workspace; other endpoints may differ.

PolicyStopped

The guard rejected the action. Inspect the policy reason rather than retrying the callback without a guard.

PolicyUnavailable

The SDK could not obtain fresh valid policy. Guarded calls fail closed; restore connectivity or retry safely.

Missing evidence

Call seal after the run ends. Check its result and delivery status. The Python SDK returns None if sealing cannot complete.

SDK references

Python package and README · TypeScript package and README

Need help with a pilot integration? Email info@traceryx.com with the SDK version, run ID, and a sanitized error. Do not send API keys or customer payloads.