Where the write goes

The write is one HTTP call with your workspace's key in a header. The question for an agent is which process makes that call. The answer is the same in every setup: the process that runs the agent, never the model itself.

Why not the model#

A key the model can read is a key the model can print, paste into a tool call, or be talked into revealing. A key the model cannot read cannot leave through the model. So the key lives in the harness, the runtime, or a service beside it, and the write is made there, with the agent's name in actorId and the instruction's source in instructedBy. The model never sees the key and never needs to.

The same holds for the fingerprints. Fingerprint the file where the harness holds it; the model never handles the bytes.

Three setups#

The harness writes. The code that runs the agent loop already sees every tool call and every result. After each action it writes the entry, from the same process, with the key from its own environment. This is the simplest setup and the one to start with.

const pac = new PacSpace({ apiKey: process.env.PACSPACE_API_KEY! }); // the harness's environment, never the model's context

for await (const step of runAgent(instruction)) {
  const result = await tools.run(step);            // the action happens
  await pac.records.emit({                          // then it is recorded
    record: `run-${runId}`,
    title: describe(step, result),                  // your words, at most 120 characters
    kind: step.tool,                                // 'read', 'ticket-close', 'email'
    occurredAt: result.at,
    actorId: agentName,
    instructedBy: requestedBy,
    payloads: [await fingerprint(result.bytes)],
    idempotencyKey: `run-${runId}:step-${step.id}`,
  });
}

A recording tool. The agent has a tool it can call, record_action, and the tool's implementation makes the write. The model decides when to record; the harness decides how, and holds the key. Use this when the agent runs in a framework where you do not control the loop, and pin actorId and instructedBy inside the tool rather than taking them from the model.

A sidecar. A separate service receives the agent's events (from a message bus, a log stream, or the framework's callbacks) and writes them. The agent's process never holds the key at all. Use this when many agents share one workspace or when the agent's runtime is not yours.

The order of things#

Record the action after it happened. occurredAt is the time of the action, and an entry written before the action is a record of an intention. If the write fails, the action still happened; retry the write with the same idempotency key until it is queued, and read the history or wait for record.committed to know it landed. See Safety and idempotency.

What the write does not need#

No network access from the model. No secrets in the agent's memory. No changes to the agent's prompt. No approval from PacSpace: a records workspace writes with its key, and the entry is committed or fails with a code the harness can read.

What the record shows a reader#

On the Shared Record, each entry shows the writer and the actor as two facts: "Written by Northwind Robotics, harness key" and "support-agent-3 is who acted. It does not hold this key." That line is the point of this page. The reader can see that the agent did the thing and that the agent did not hold the means to change the record of it.