The agent inventory, which agents exist and who answers for them.

The inventory answers the first question a board asks about agentsAgentA program that takes actions for an organisation. NovusLens records what it is allowed to do and what its activity reports show.: which agents exist, what each one serves, what each one may decide, and who is accountable. It is one JSONJSONJavaScript Object Notation: a text format for data, using named fields, lists and values. Configuration files and service messages use it. file with two lists. The first list holds platform-signed AgentFactsAgentFactsA signed statement from an agent about its allowed work, its permissions and the person answerable for it. documents, which land at the shownShownEvidence that a document supports a value. A recovery plan that states a target shows the target, but it does not show that the target was achieved. rungRungOne of three levels of support for a recorded value: told, shown or measured. The level appears beside the value.. The second holds entries typed by hand, which land at the toldToldEvidence that somebody stated the value. It is the weakest level, and it is always attributed to its speaker. rung, confirmed by the person who imported them.

Grants of authorityAuthorityWhat a team or agent is allowed to decide or do. For an agent, this comes from a named person or system that grants permission., operations, interventions, outcomes and activity are not in this file. They are evidence, and they arrive as signed records from an enrolled sourceSourceA document, interview statement, measurement or export that supports a value. Each source has a date and a stated scope.. A remitRemitA written list of an agent’s allowed actions, resources and destinations for information. The list states whether it is complete. is the one exception, and it is declared in the product. Until a source sends activity, the second board question is answered “authority not established” or “cannot be stated”. That is the honest answer, and the mapMapThe view of teams, services and their dependencies for the selected part of the organisation. Details appear beside the map. should not be read as more than that.

Before you start

The customer route

On a customer installation, agents arrive as signed evidence from an enrolled source, not from this file. Enrol the source, activate it, and have its producer send signed batches. See Agent evidence contract v1 for the steps and the record types. The page you are reading covers the bundle format, which a development or demonstration installation reads.

Before you start (development or fixture installation)

You need the installation running and the meshMeshA set of connected Mycelium services that exchange updates and keep the NovusLens log. node reachable. The command waits for the node to report healthy before it writes.

You also need the name of the person who confirms the hand-typed entries. The command takes this as --attest-by. The attestation is labelled with that name, and it is required whenever the file has hand-typed entries. A customer installation refuses --attest-by: there, the operator loads the file under Administration → Load the agent inventory, and the signed-in person is the attester.

A source checkout has a template at apps/connectors/fixtures/agentfacts_template.json. It has an empty agents list and one example entry under attested. Copy it, and fill in one entry for each automation in your estate.

The bundle

The file has two top-level lists:

Either list may be empty. A development or fixture file usually has only attested. A customer installation cannot ingestIngestRead supplied records or documents and add their information to NovusLens, after the required checks. attested entries from the command line.

A signed envelope has four parts: document, the fields described below; alg, which is ed25519; public_key_b64, the signer’s public keyPublic keyA value used to check a digital signature. Sharing it lets others check signatures but does not let them create new signatures.; and signature_b64, the signatureDigital signatureA check calculated with a signing key that can detect whether a record has changed. Identifying the signer also requires a trusted link between that key and its owner. over the document. The parser reads the fields from the document part.

Fields per entry

Worked example (illustrative)

The agent below is an example. It is not a real automation.

{
  "agents": [],
  "attested": [
    {"agent_id": "customs-prefill", "label": "Customs pre-fill assistant", "serves": "customs",
     "declared_capability": "declaration-prefill",
     "granted_authority": "drafts declarations; a person files them",
     "accountable_owner": "Head of Customs"}
  ]
}

The connectorConnectorSoftware that reads records from a source system, such as an incident tool. A customer-written file connects those records to teams or services in NovusLens. test checks the guide’s example through the same bundle parser the command uses. It confirms that the example has no signed agents and one attested agent.

How to send it (development or fixture only)

Every installation that ./lens setup creates runs the customer profile, which refuses this command as described above. Run it in the development runner, from the root of a source checkout:

./lens ops --version dev exec -- uv run python -m conway_connectors --org harbour agents --fixture agents.json --attest-by operator

The command takes --fixture, which is required, --attest-by, and --solicited-by. The last one names an open request for the artefactArtifactA stored source file or evidence body that a record can cite. Keeping the exact content lets a reader check what supported the record., if one exists.

On success the agents command prints one line in this form: agents: N platform-signed mapped (shown) · M operator-attested mapped (told, attested by X) · K refused unverified. Malformed documents are not counted in it.

The signed-only command

A second command, agent-facts, takes a file with the same agents list and no attested list. It runs the same pipeline. It has no --attest-by flag. A file that holds attested entries is therefore refused, with a message that asks for an attester this command does not accept. Use agents for a file with attested entries.

./lens connectors agent-facts --org harbour --fixture signed-agents.json

It prints a different line: agent-facts: N declared → M mapped (names; artifact id), with the names of any refused documents, and malformed documents flagged by their position in the file.

What you will see

The command stores the file as an evidence artefact. Each mapped agent becomes a node on the map, parented on the cell it serves, and marked as external. NovusLens reads evidence reported at the agent’s boundary. It does not run the agent. A signed agent’s declared structure and authority cite the stored file, so the citation resolves to it.

Each attested agent becomes a node at the told rung. The stored artefact records the attester’s name against each attested entry. The record carries the named attester and a signature that detects changes. Its public name-derived key does not establish who typed it.

The map shows the result after the projectionProjectionThe regular pass that brings the read model up to date with the canonical log. It runs every 30 seconds by default. service’s next pass, which the guide puts at about 30 seconds by default.

What a re-run does

A re-run follows these rules.

Refusals and findings

• Attested entries without --attest-by. The whole bundle is refused before anything is written. The error says to pass --attest-by, and says that the entries will land at the told rung, labelled as operator-attested.
• Customer profile, attested entries. Refused. In the customer profile the command refuses every attested entry, because attestation from the command line is unavailable. The message says that customer attestation needs an authenticated session.
• Customer profile, signed documents. Refused, because the command has no enrolled subject keys. The message names the file and its agents, and gives the command that takes signed AgentFacts with enrolled keys: ./lens connectors boundary --org <org> --gateway <host:port> --enrolment <file>.
• Signed document that does not verify. Not mapped. An agent-facts-unverified finding opens. The finding does not close when a corrected file arrives.
• Signed document with no agent_id. Not mapped. An agent-facts-malformed finding opens.
• Attested entry with no agent_id. Not mapped. No finding opens, and the command does not print it.
• Unknown serves. The agent is mapped, but it is not parented on any cell and no edge is drawn. No finding opens.

Signature checks are against the public key embedded in each document. The development path checks the signature against the key in the document. It does not establish that this key belongs to a trusted platform.