Integrate a raw customer agent repo with Veris end to end. Installs or verifies veris-cli, logs in, creates or reuses a Veris environment, analyzes the repo, generates or updates `.veris/veris.yaml`, `.veris/Dockerfile.sandbox`, `.veris/.dockerignore`, configures runtime env vars, and can finish wit

Integrate this agent repo with Veris from scratch. This skill takes a repo from "plain customer agent source" to "Veris ready and pushable." If the user provided a path to an agent repo, use that as the repo root. Otherwise use the current working directory. Treat any existing .veris/ files or old scaffold output as starting material only. Use the current bundled references in this skill as the source of truth for what you generate. Core framing: the agent is the constant, Veris is the test harness Veris exists to test an agent under realistic conditions. The agent is the thing being tested; Veris is the harness around it. That asymmetry drives every decision in this skill: The agent runs the same way in Veris as it does in production. If the agent speaks HTTP to a Slack Web API in prod, it speaks HTTP to the Veris Slack mock in sim. If it shells out to a CLI in prod, it shells out in sim. No special simulation code path. All integration work lives in .veris/ . .veris/veris.yaml , .veris/Dockerfile.sandbox , .veris/config.yaml , .veris/.dockerignore are the deployment descriptor — the equivalent of a Helm chart or docker compose.yaml for this agent. They describe how to stand the agent up for this environment . They do not contain behavior that belongs inside the agent. Do not write wrappers, shims, or glue code that "adapts" the agent to Veris. A Python file that wraps a CLI agent to expose a callable, a script that translates Veris's actor format into the agent's native format, a patched version of the agent that accepts Veris specific parameters — all of these are the wrong shape. They mean the thing you end up testing is not the agent. Do not modify the agent's source code to make it work in Veris. If the agent assumes something Veris can't satisfy as is, that's either a Veris platform gap to be logged, or a real issue with the agent that would also break production. Either way, the fix does not belong in the agent's source. If you find yourself needing a wrapper, stop and treat it as a finding. Ask: what is the agent's real production integration path? If the agent has an HTTP server in prod, use that. If it's CLI only in prod and Veris's actor can't drive a CLI, escalate — that's a Veris capability gap, not a license to invent glue. The one legitimate .veris/ file that is not pure config is a container orchestration start.sh for bundling multiple processes (e.g., a database alongside the agent). Even that starts and runs the agent as shipped; it does not transform its behavior. When in doubt: the agent's author should be able to read .veris/ and recognize it as "the deploy config for Veris," not as "someone forked and patched my agent." Transport bridges are an explicit exception A transport bridge translates between the actor's channel format (e.g. voice ws PCM16) and the agent framework's native transport (e.g. LiveKit WebRTC, SIP media, a proprietary message envelope) while preserving the underlying payload byte for byte. It is not a wrapper. The same shape exists in production for the agent's other product surfaces — mobile clients, kiosks, IVR vendors — so the bridge is genuine product code, not Veris specific glue. A bridge is allowed when: The agent's framework cannot be reconfigured to speak the actor's channel format directly (e.g., LiveKit Agents is WebRTC end to end and has no raw PCM16 WS transport). The bridge is pure transport translation: same audio bytes / same JSON payloads in and out, with no semantic reshaping. (For voice, the audio bytes the agent's model receives must be identical to what the actor sent. For text, the message payload the agent sees must be identical to what the actor sent.) The bridge lives in the agent's repo as production code (e.g., app/bridge.py ), exercised by the agent's own tests — not in .veris/ . It is the agent's voice ws on WebRTC product surface; Veris is just one caller. A bridge is not allowed when: It reshapes content the agent sees: rewriting messages, restructuring tool call JSON, normalizing STT output, translating Veris specific actor fields into the agent's native parameters. That is a wrapper, and the no wrapper rule above applies. The framework can be configured to speak the actor's channel (Pipecat with RawAudioFrameSerializer for voice ws , the framework's own HTTP plugin for http , etc.). Configure the framework first; bridge only if the transport is fixed. Quick rubric: "same bytes, different network format" = transport bridge (allowed). "Different bytes / different shape" = wrapper (not allowed). See [reference/infrastructure patterns.md Pattern 9](reference/infrastructure patterns.md pattern 9 transport bridge) for the architecture and [reference/voice channels.md](reference/voice channels.md) for the voice specific application. Reporting client tool calls to the grader is a sanctioned exception (voice agents only) This is the one exception that genuinely breaks the "no Veris specific code path" rule — and it is deliberate. It applies only to voice agents built on hosted speech to speech platforms (ElevenLabs Conversational AI, OpenAI Realtime, Gemini Live, Vapi, and the like) whose tools execute inside the agent process — as client tools that round trip on the vendor's WebSocket, or as Vapi style server tools the platform POSTs back to the agent's webhook over HTTP. Either way the call never reaches the spoken transcript. Why it's needed: the voice grader builds its trace from the spoken transcript plus any tool call events the agent reports. A client tool never reaches the transcript, so without a report the grader can't see the tool ran and false flags real actions (a card freeze, a replacement) as hallucinations. Text/HTTP agents don't have this problem — their tool calls are captured automatically — so this exception is voice only. The fix: after each tool runs, the agent POSTs an agent tool call event to the sandbox engine, and the platform renders it into the graded trace. Keep it strictly minimal so it stays instrumentation, not a wrapper: No op outside a simulation. Gate on SIMULATION ID (unset in production → return immediately). Production behavior is unchanged. Fire and forget, fail soft. Short timeout, swallow errors, log a warning. A reporting failure must never break the call or change the agent's output. Observe, don't reshape. Report after the real tool runs, passing the real name/args/result through unchanged. It records what happened; it does not alter what the agent does or what the model sees. This is sanctioned only for client tool grader visibility, only for voice agents, and only in this minimal shape — it is not a license for general shims. The exact endpoint, event schema, and a copy paste hook are in [reference/voice channels.md](reference/voice channels.md making client tool calls visible to the grader). Core rules Explain what you are about to do before each major step. Surface decisions with real tradeoffs and let the user choose. Cite concrete evidence from the repo when you classify dependencies or decide how the agent should be integrated. Do not silently preserve stale Veris config. Migrate it to the current preferred shape. Do not generate .env.simulation . The current runtime flow is agent.environment plus veris env vars set . Prefer the current actor.channels schema and canonical service names. Do not generate legacy persona.modality , email address , or old service aliases unless the user explicitly asks for compatibility. Do not write Python wrappers, shell shims, or any "adapter" code that translates between Veris and the agent. Use the agent's real production interface. If that isn't possible as is, surface it as a platform gap, not as a wrapper opportunity. Ask before external or irreversible actions: installing veris cli running veris login running veris env create setting environment variables with veris env vars set pushing with veris env push Fast track mode If the user says "go all the way", "do everything", or otherwise pre approves the full flow: Skip intermediate checkpoints (end of Phase 2, end of Phase 3, end of Phase 4) Still explain decisions inline as you make them, so the user can follow along Still stop and ask before truly irreversible or external actions: veris env create , veris env push , veris env vars set with real secrets If a decision has genuinely ambiguous tradeoffs (e.g., bundle vs external for a heavy service), pause and ask even in fast track mode At the end, present a consolidated summary of all decisions made Read these files when needed For current service names and detection: [reference/service mapping.md](reference/service mapping.md) For env overrides and mock credentials: [reference/env var overrides.md](reference/env var overrides.md) For bundleable local infra: [reference/bundling recipes.md](reference/bundling recipes.md) For container restructuring patterns: [reference/infrastructure patterns.md](reference/infrastructure patterns.md) For voice agents ( voice ws channel, framework choice, trailing silence, reporting client tool calls so the grader can see them ): [reference/voice channels.md](reference/voice channels.md) For current veris.yaml structure: [reference/veris yaml schema.md](reference/veris yaml schema.md) For generated config examples: [templates/veris yaml.md](templates/veris yaml.md) For Dockerfile patterns: [templates/dockerfile sandbox.md](templates/dockerfile sandbox.md) For runtime env var handling: [templates/env vars.md](templates/env vars.md) For multi process startup scripts: [templates/start sh.md](templates/start sh.md) For integration failures: [phases/troubleshooting.md](phases/troubleshooting.md) Workflow Overview Phase Goal 0 Bootstrap Veris tooling and environment 1 Discover the repo and current runtime 2 Analyze dependencies and service strategy 3 Choose integration mode and container architecture 4 Generate .veris/veris.yaml 5 Generate .veris/Dockerfile.sandbox and supporting files 6 Configure runtime env vars, validate, and push 7 Smoke validate with a single scenario + simulation Phase 0: Bootstrap Veris Tooling And Environment [Phase 0/7] Tell the user: "I'm going to make sure this repo has the Veris tooling and environment wiring needed for the rest of the integration work." 0.1 Verify repo root Confirm the directory is an agent repo, not just a parent folder. Look for source code, dependency manifests, and app entrypoints. 0.2 Verify veris cli Check whether veris is installed and working. If not installed: Prefer uv tool install veris cli Fallback: pip install veris cli Explain which install path you are using and why. 0.3 Verify Veris authentication Check whether the user is already logged in and which profile/backend they are using. If not authenticated: Recommend veris login for browser auth Use API key login only if the user explicitly prefers it Do not proceed to veris env push until auth is working. 0.4 Verify or create .veris/ Inspect: .veris/config.yaml .veris/veris.yaml .veris/Dockerfile.sandbox .veris/.dockerignore If .veris/ does not exist, or it exists but has no environment binding: 1. Derive a candidate environment name from the repo directory. 2. Show the user the proposed name. 3. On approval, run veris env create self serve name "<name " . self serve ( veris cli = 2.27.0 ) is the right mode for this skill's audience: you are authoring .veris/ yourself, and the env should be ready for veris env push immediately. Without it, env create defaults to managed setup mode where the Veris team generates Dockerfile.sandbox + veris.yaml for the customer, and veris env push returns 409: Run veris env s

agent-integration