Artifacts

Traces capture execution. Artifacts encode improvement. A trace is the recording - an artifact is the fix.

Installnpm install @chronicle-labs/sdk

SDK generation in progress - until published, Node 18+ fetch works with no extra dependencies.

Endpoints

Method	Path	Status
`GET`	`/v1/artifacts`	Beta
`GET`	`/v1/artifacts/{id}`	Beta
`GET`	`/v1/traces/{id}/artifacts`	Beta

The artifact object

An artifact is generated from a trace after it has been evaluated and deemed incorrect or risky. It contains the failing trace reference, the expected outcome based on SOP or verifier judgment, the failure classification, and the recommended constraint or context needed to prevent it.

Artifacts answer: "What should change so this does not happen again?"

failure - description of what went wrong, classification tags, and the failing step index.
expected_behavior - what the agent should have done according to policy or verifier judgment.
correction - machine-readable rule or constraint the developer applies to fix the agent.
confidence - verifier confidence score for the correction (0-1).
source_trace_id - the trace this artifact was generated from.
agent_id - the agent that produced the failing trace.

The Chronicle loop

Simulate workflow -> Capture trace -> Evaluate trace -> If incorrect, generate artifact -> Developer applies constraint -> Re-run simulation -> Failure disappears. That's the closed loop.

List artifacts

Query artifacts across traces. Filter by tenant, agent, type, and failure tags.

tenant_idstringrequired

Tenant namespace.

agent_idstring

Filter by agent.

typeenum

Artifact type: "correction", "constraint", "context_addition".

tagsstring[]

Filter by failure tags (repeatable).

limitinteger

Max artifacts to return (default 25, max 1000).

offsetinteger

Number of results to skip (default 0).

Node

const artifacts = await chronicle.artifacts.list({
  tenant_id: "tenant_demo",
  agent_id: "refund_agent_v2",
  tags: ["out_of_policy"],
  limit: 20,
});

Response

JSON

{
  "artifacts": [
    {
      "artifact_id": "art_01J8XQZW9NKV",
      "source_trace_id": "trc_01J8XNR3KMPQ2VWYZ",
      "agent_id": "refund_agent_v2",
      "type": "correction",
      "failure": {
        "description": "Agent issued a $49.99 refund without manager escalation",
        "tags": ["out_of_policy", "missing_escalation"],
        "step_index": 1
      },
      "expected_behavior": "Refunds above $25 require escalation to a manager before processing",
      "correction": {
        "rule": "If refund amount > 2500 cents, call escalation_api.request_approval() before refund_api.create()",
        "confidence": 0.94
      },
      "created_at": "2026-02-21T10:35:00Z"
    }
  ],
  "count": 1,
  "has_more": false
}

Retrieve an artifact

Fetch the full artifact including the correction rule, failure details, and source trace reference.

Node

const artifact = await chronicle.artifacts.retrieve("art_01J8XQZW9NKV");

Response

JSON

{
  "artifact_id": "art_01J8XQZW9NKV",
  "source_trace_id": "trc_01J8XNR3KMPQ2VWYZ",
  "agent_id": "refund_agent_v2",
  "type": "correction",
  "failure": {
    "description": "Agent issued a $49.99 refund without manager escalation",
    "tags": ["out_of_policy", "missing_escalation"],
    "step_index": 1
  },
  "expected_behavior": "Refunds above $25 require escalation to a manager before processing",
  "correction": {
    "rule": "If refund amount > 2500 cents, call escalation_api.request_approval() before refund_api.create()",
    "confidence": 0.94
  },
  "applied": false,
  "created_at": "2026-02-21T10:35:00Z"
}

List artifacts for a trace

Fetch all correction artifacts generated from a specific trace. This is the same endpoint documented in the Traces API - included here for discoverability.

Node

const artifacts = await chronicle.traces.artifacts("trc_01J8XNR3KMPQ2VWYZ");

Response

JSON

{
  "trace_id": "trc_01J8XNR3KMPQ2VWYZ",
  "artifacts": [
    {
      "artifact_id": "art_01J8XQZW9NKV",
      "type": "correction",
      "failure": { "description": "Agent issued a $49.99 refund without manager escalation", "tags": ["out_of_policy"] },
      "correction": { "rule": "If refund amount > 2500 cents, call escalation_api.request_approval()", "confidence": 0.94 },
      "created_at": "2026-02-21T10:35:00Z"
    }
  ],
  "count": 1,
  "has_more": false
}

Artifact types

correction - a rule or constraint that prevents the specific failure from recurring.
constraint - a guardrail to add to the agent's execution boundary (e.g. max refund amount before escalation).
context_addition - additional context or instructions to inject into the agent's prompt to improve judgment.

Applying artifacts

Artifacts are designed to be machine-readable so they can be applied programmatically. The typical workflow:

Fetch artifacts for an agent: GET /v1/artifacts?agent_id=refund_agent_v2
Read the correction.rule field for each artifact.
Add the rule as a constraint or instruction in your agent's configuration.
Re-run the simulation in a sandbox to verify the failure disappears.
Graduate the agent to production.