Quickstart

What you will build

In about 10 minutes you will create an Agent Genome, run an agent with signed tracing, verify the signed Evidence Ledger, generate an Evidence Package, evaluate technical evidence for EU AI Act workflows, and optionally connect the MCP Server so agents can write their own evidence trail. Some commands below show the target Agenomic CLI surface; where one is not yet wired in your build, treat it as planned and substitute your internal equivalent.

• Install the CLI.
• Create an Agent Genome.
• Run an agent with tracing enabled.
• Verify the signed Evidence Ledger.
• Generate an Evidence Package.
• Evaluate technical evidence for EU AI Act workflows.
• Connect the MCP Server so agents can call Agenomic directly.
• Prepare the setup for production.

1. Install Agenomic

Install the agenomic CLI with Homebrew, the shell installer, or npm, then confirm the version. If a package channel is not published for your environment yet, treat that command as planned and replace it with your internal install command. Every local step below runs offline, with no account.

# Homebrew
brew install agenomic/tap/agenomic

# Shell installer
curl -fsSL https://agenomic.io/install.sh | sh

# npm
npm install -g @agenomic/cli

# Confirm the install
agenomic --version

2. Create an Agent Genome

An Agent Genome is the signed, portable record of what defines an agent release: prompts, models, tools, policies, permissions, dependencies, memory contracts, traces, metrics, replay reports, and evidence. Scaffold one with agenomic init.

agenomic init

# or write to a named file
agenomic init genome.yaml

Define genome.yaml

A minimal genome pins the model, system prompt, tools, policy governance rules, and memory contract.

agent:
  id: customer-support-agent
  version: 0.1.0

model:
  provider: openai
  name: gpt-4.1
  temperature: 0.2

prompts:
  system: ./prompts/system.md

tools:
  - name: crm.lookup
    schema: ./tools/crm.lookup.json
  - name: email.send
    schema: ./tools/email.send.json

policies:
  - ./policies/pii-email-review.yaml

memory:
  contract: ./memory/contract.yaml

Verify the genome

Resolve and validate the genome before you run it. Verification confirms that tools, policies, and dependencies resolve, and records the canonical genome hash.

$ agenomic genome verify genome.yaml
✓ genome valid
✓ tools resolved
✓ policies resolved
✓ genome hash: sha256:4f8c2ab9...

3. Run with tracing

Agenomic captures a canonical trace for each run. Events are append-only, hash-chained, and can be sealed into a tamper-evident Evidence Ledger.

$ agenomic run agent.yaml
✓ run started: run_01...
✓ genome resolved
✓ prompts captured
✓ tools locked
✓ policies checked
✓ events signed
✓ run completed

Core event types

Each run emits a canonical, append-only sequence of events. Agenomic does not require storing raw prompts or tool payloads in logs — production setups store hashes and redacted payloads by default.

run.started
genome.resolved
llm.requested
llm.responded
tool.call.proposed
policy.check.performed
tool.call.executed
tool.result.observed
run.completed

4. Verify the ledger

Verification proves the technical integrity of the recorded run: the hash chain, the Merkle root, and the signature. It does not by itself provide legal certification.

$ agenomic runs verify run_01...
✓ hash chain valid
✓ merkle root valid
✓ signature valid
✓ trace completeness: 1.00

5. Generate an Evidence Package

An Evidence Package collects the genome snapshot, signed Evidence Ledger, verification report, metrics, and compliance mapping into one signed archive.

$ agenomic evidence generate run_01...
✓ manifest.json
✓ genome_snapshot.json
✓ event_ledger.jsonl
✓ ledger_verification.json
✓ trace_completeness.json
✓ compliance.json
✓ metrics.json
✓ signatures.cat

evidence_package.zip created
audit evidence completeness: 0.94

Verify the Evidence Package

Verify a package end to end before you share it. Never present a simulation or synthetic replay as probative evidence — Agenomic labels simulations as non-probative.

$ agenomic evidence verify evidence_package.zip
✓ package hash valid
✓ manifest signature valid
✓ member hashes valid
✓ simulation artifacts excluded from probative evidence

6. Evaluate EU AI Act technical evidence

Agenomic maps runs and releases to technical evidence workflows for risk management, technical documentation, record-keeping, and human oversight. It generates technical evidence and supports EU AI Act workflows; it does not certify compliance, and legal compliance requires qualified review.

$ agenomic compliance evaluate run_01... --profile eu-ai-act
Article 9   risk management              pass
Article 11  technical documentation      pass
Article 12  record keeping               pass
Article 14  human oversight              warning

Technical evidence generated.
Legal compliance requires qualified review.

7. Compare two releases

Agenomic compares the Agent Genome and the observed behavior, not just source files, so reviewers see behavioral drift before promotion.

$ agenomic diff baseline.lock candidate.lock
prompt_changed: true
tool_changed: false
policy_changed: true
model_config_changed: false
behavioral_drift: 0.08

8. Replay a run

Replay re-derives a run for verification. exact mode attempts a hash match; when a provider is non-deterministic, Agenomic falls back to functional equivalence and reports a fidelity score.

$ agenomic replay run_01... --mode exact
exact replay unavailable: provider_non_deterministic
fallback: functional
replay fidelity: 0.97

Evidentiary replay

Evidentiary replay proves a run from signed artifacts with no re-execution — the basis for audit-ready evidence.

$ agenomic replay run_01... --mode evidentiary
✓ no re-execution required
✓ ledger integrity valid
✓ evidence completeness valid
✓ policies verified

Replay modes

Agenomic supports five replay modes, from strict reproduction to proof without re-execution.

• exact — hash match.
• functional — equivalent result.
• statistical — stable distribution over N runs.
• explanatory — causal graph and root cause.
• evidentiary — proof from signed artifacts, no re-execution.

9. Use the Python SDK

The SDK mirrors the CLI for programmatic runs, events, verification, and evidence. Keep secrets and raw payloads out of trace bodies.

from agenomic import Client

client = Client(api_key="agenomic_dev_key")

run = client.runs.create(
    agent_id="customer-support-agent",
    genome="genome.yaml",
)

client.runs.append_event(
    run_id=run.id,
    type="tool.call.proposed",
    actor={"kind": "agent", "id": "customer-support-agent"},
    payload_hash="sha256:...",
)

verification = client.runs.verify(run.id)

package = client.evidence.generate(run.id)

10. Connect the MCP Server

Agents can use Agenomic directly through MCP. The Agenomic MCP Server lets compatible LLMs, agents, IDEs, and runtimes call Agenomic tools while they run. Add it to your client config — this is a first-class path, not an afterthought.

{
  "mcpServers": {
    "agenomic": {
      "command": "agenomic-mcp-server",
      "args": ["--transport", "stdio"],
      "env": {
        "AGENOMIC_API_BASE_URL": "http://localhost:8080",
        "AGENOMIC_MCP_REQUIRE_AUTH": "false"
      }
    }
  }
}

Available MCP tools

The server exposes tools for runs, genomes, policy governance, evidence, compliance, metrics, drift, and replay.

agenomic.start_run
agenomic.append_event
agenomic.complete_run
agenomic.verify_run
agenomic.register_genome
agenomic.release_genome
agenomic.diff_genomes
agenomic.evaluate_policy
agenomic.record_human_review
agenomic.generate_evidence_package
agenomic.verify_evidence_package
agenomic.evaluate_compliance
agenomic.compute_metrics
agenomic.detect_drift
agenomic.replay_run
agenomic.send_later

Example agent flow

A typical agent governs its own actions over MCP: start a run, propose a tool call, check policy, request human review when required, execute, complete, verify, and emit evidence. MCP outputs are redacted by default — raw prompts, completions, tokens, secrets, and sensitive payloads are not exposed unless explicitly enabled in a controlled environment.

1. start_run
2. append_event tool.call.proposed
3. evaluate_policy
4. request human review if required
5. append_event tool.call.executed
6. complete_run
7. verify_run
8. generate_evidence_package

11. Production setup

Before Agenomic handles production traffic, turn on authentication, isolation, signing, and observability.

• Enable authentication and use org-scoped tokens.
• Enable row-level security (RLS).
• Store raw payloads outside the database.
• Redact sensitive logs.
• Enable Evidence Ledger sealing.
• Enable Evidence Package signing.
• Configure object storage with retention or WORM where available.
• Configure KMS or signing keys.
• Enable OpenTelemetry traces and Prometheus metrics.
• Configure health and readiness checks.

Environment variables

A representative production configuration.

AGENOMIC_ENV=production
AGENOMIC_API_BASE_URL=https://api.agenomic.io
AGENOMIC_LOG_FORMAT=json
AGENOMIC_LOG_LEVEL=info

AGENOMIC_TRACING_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317

AGENOMIC_METRICS_ENABLED=true
AGENOMIC_METRICS_PATH=/metrics

AGENOMIC_REDACT_SENSITIVE_FIELDS=true
AGENOMIC_INCLUDE_SQL_VALUES=false

AGENOMIC_MCP_ENABLED=true
AGENOMIC_MCP_REQUIRE_AUTH=true
AGENOMIC_MCP_ALLOW_MUTATING_TOOLS=true
AGENOMIC_MCP_EXPOSE_SENSITIVE_RESOURCES=false

12. Production observability

Agenomic should emit structured JSON logs, OpenTelemetry traces, Prometheus metrics, and request and trace IDs, plus worker job, Evidence Ledger verification, Evidence Package, compliance evaluation, replay, and drift metrics.

agenomic_http_requests_total
agenomic_ledger_events_appended_total
agenomic_ledger_integrity_failures_total
agenomic_evidence_packages_generated_total
agenomic_compliance_evaluations_total
agenomic_replay_runs_total
agenomic_drift_alerts_total
agenomic_mcp_tool_calls_total

13. Security model

By default, Agenomic logs and exposes integrity metadata, never raw sensitive content.

• Allowed: hashes, IDs, redacted payloads, policy results, metrics, and verification status.
• Never exposed: raw prompts, raw completions, API keys, authorization headers, cookies, email bodies, object-storage signed URLs, and sensitive tool arguments.

14. Next steps

You have gone from a local run to a signed Evidence Package and connected agents to Agenomic over MCP. Dig into the Agent Genome model in Concepts, the CLI reference and Python SDK, and the EU AI Act evidence guides linked below; revisit the MCP Server, Evidence Package, replay, and drift sections above for production detail. To start for real, create your first genome with agenomic init.

• Concepts — the Agent Genome, Evidence Ledger, and replay model.
• CLI reference and Python SDK.
• EU AI Act evidence: compliance overview, technical documentation, and audit trail.
• MCP Server, Evidence Package, replay modes, drift detection, and production observability — covered in the sections above.