Add your agent to Veris Bench

Take the agent in this repository to a registered Your image candidate on a Veris Bench bench, and prove it works with a smoke trial.

The agent is the constant. Add one server file, a Dockerfile and a candidate file beside the agent. Change the agent's own code only when there is no other way, and say so in your report.

A smoke attempt that is

completed

does not prove the integration works. An agent whose database calls all fail, or whose model calls the grader cannot see, still completes. Step 9 says what to check.

Read

reference/api.md

before step 1 and

reference/image.md

before step 2.

Inputs

Collect these before you change anything. Ask the user for what is missing.

Input	Where it comes from
`VERIS_API_KEY`	Environment variable, starts with `vbk_` . Only a person can issue one: console, Overview, API keys, Issue. Never print it or write it to a file.
`BENCH_API`	Default `https://bench.api.veris.ai/v1` . Use another only when the user gives one.
`BENCH_ID`	The skill's argument, if the user gave one. Otherwise ask, or list their benches and have them choose.
Registry	A repository prefix Docker can push to, such as `ghcr.io/<org>` .
Model keys	The secrets the agent reads, such as `OPENAI_API_KEY` . They go in the bench, never in the image or the repository. The user adds a missing one in the console, unless it is already in your environment.

Steps

Check access. Read the bench.
```
access
```
must be
```
write
```
. If it is
```
read
```
, stop and tell the user why (
```
reference/api.md
```
, "Access").
Read the agent, without editing. Write down: language and entry point; the function that runs one conversation turn and how it keeps history; the model SDK and its installed version; every external service it calls and where each address or DSN comes from (variable, config file or a literal); every secret it reads; and files it opens by a relative path. Check the SDK against "Telemetry" in
```
reference/image.md
```
now: an unsupported version records no model calls and says nothing.
Read the bench's world. List its services (
```
reference/api.md
```
, "World"). Match each service the agent calls to a twin. Tell the user about any service the agent calls that has no twin: those calls reach the real vendor, unless Veris turned on the gateway for the bench.
Add the server file,
```
bench_server.py
```
or
```
bench_server.mjs
```
, from the pattern in
```
reference/image.md
```
. It wraps the agent's turn function, keeps one conversation per session id, serves
```
/health
```
, and listens on
```
0.0.0.0:8008
```
. Use http. Use ws only if the agent already speaks WebSocket.
Point the agent at the twins, in the server file. Before the agent's modules load, copy each twin's address from
```
VERIS_DS_SERVICE_URLS
```
into the setting the agent already reads. Apply the client fixes in
```
reference/image.md
```
, "Twins".
Write the Dockerfile and
.dockerignore
from
```
reference/image.md
```
. If the repository has a Dockerfile, reuse it when it can run the server.
Check locally. Build for
```
linux/amd64
```
, run it, and send
```
/health
```
and one turn (
```
reference/image.md
```
, "Local check"). Fix anything that fails here before you push.
Push and register. Push, pin by digest, run
```
check-image
```
, save a registry login if needed, make sure each secret is in the bench's candidate-env, write
```
bench/candidate.json
```
, and register the candidate (
```
reference/api.md
```
).
Run a smoke trial and verify it. Two tasks that need the agent's tools, no personas, one repeat. When nothing is pending, check every attempt against the table below. Each row that fails is an integration bug: find the cause in its artifacts, fix it, push a new digest, update the candidate, re-run it in the same trial once nothing is pending, and check again.
Report (format below).

Done means every smoke attempt shows this

Check	Where to read it ( `reference/api.md` , "Verify")	If it fails
It ran	`status` is `completed`	Read the end of `error` : it holds your container's last log lines.
The agent answered	`turns` is 2 or more, and the transcript has agent replies	Wrong path or field mapping, or the server crashed on a turn. Read `candidate.log` and `transcript.jsonl` .
The grader sees the model calls	`agent_trace_reason` is `null` , and `agent_trace.json` has `llm_calls` above 0	See "Telemetry" in `reference/image.md` . `agent_trace_reason` alone is not enough: it is `null` when the trace holds no model call. `judge_disabled_trace` means the bench's grader doesn't read traces: not a bug, skip this check.
The agent used its tools	`tool_calls` above 0 if the agent has tools, and the tool results in `agent_trace.json` are not errors	A tool error that names a connection or a certificate is step 5; read "Twins" in `reference/image.md` .
It reached the twins	each twin the agent uses received at least one request from it ( `reached` in the Verify command)	The agent is still pointed at its own default address. Redo step 5. Don't use `ledger_summary` counts for this: they include requests the platform makes.

passed

is not on this list. Whether the agent passes a task measures the agent, not the integration. Two attempts say little about quality; a full trial does.

Traps that look like success

Symptom	Cause	Fix
Node agent: every database tool fails, and the log has a `pg` SSL warning	node-postgres treats the twin DSN's `sslmode=require` as `verify-full` , and the twin's certificate is self-signed	Append `uselibpqcompat=true` to the DSN in the server file
Node agent: `agent_trace_reason` is `no_spans_received`	The trace hook writes into the working directory, which the run user can't write	The run user owns the app directory ( `chown` )
Node agent: `llm_calls` is 0, and `candidate.log` has no `veris-otel-node: instrumented OpenAI` line	The `openai` package is older than 5	Upgrade `openai` to 5 or later, and update the lockfile so the image build installs it
The attempt fails within a minute, `exec format error` or a pull error	An arm64 image built on Apple Silicon, or the bench can't pull it	`--platform linux/amd64` ; run `check-image`
Agent replies are empty	`image.path` or the response field doesn't match the server	Match `bench/candidate.json` to the server
Tools fail only on the bench	A literal address, or a variable the bench doesn't set	Step 5

Report to the user

The files you added or changed, one line each.
The image reference, candidate id and trial id, and the console link
```
https://benchmark.veris.ai/benchmarks/<bench id>?trial=<trial id>
```
.
For each smoke attempt: the five checks, and
```
passed
```
.
Any change to the agent's own code or dependencies, and why.
Every fix you made after the first smoke run, and why.
Next: a full trial, as on https://docs.veris.ai/run-a-trial, and for a new version, a new candidate in the same trial.

add-your-agent

NPX Install

Tags

SKILL.md Content