agent-integration

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."

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
For env overrides and mock credentials: reference/env-var-overrides.md
For bundleable local infra: reference/bundling-recipes.md
For container restructuring patterns: reference/infrastructure-patterns.md
For current
```
veris.yaml
```
structure: reference/veris-yaml-schema.md
For generated config examples: templates/veris-yaml.md
For Dockerfile patterns: templates/dockerfile-sandbox.md
For runtime env var handling: templates/env-vars.md
For multi-process startup scripts: templates/start-sh.md
For integration failures: 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
```

.veris/

does not exist, or it exists but has no environment binding:

Derive a candidate environment name from the repo directory.
Show the user the proposed name.
On approval, run
```
veris env create --name "<name>"
```
.

Explain what

veris env create

gives them:

```
.veris/veris.yaml
```
— Veris simulation config
```
.veris/Dockerfile.sandbox
```
— image build definition
```
.veris/.dockerignore
```
— build-context exclusions
```
.veris/config.yaml
```
— environment binding for this repo

0.5 Treat scaffolding as placeholders, not truth

The generated

.veris/

files are just a starting point. They may use old defaults or generic placeholders. You are responsible for replacing them with the correct integration for this repo.

Proceed directly to Phase 1.

Phase 1: Discover The Repo And Current Runtime

[Phase 1/7]

Tell the user: "I'm going to inventory how this repo currently runs, what it depends on, and how users interact with it."

1.1 Existing Veris state

.veris/

already exists, read all existing Veris files first. Call out anything that looks stale or legacy:

```
persona.modality
```
```
email_address
```
old service names like
```
crm
```
,
```
calendar
```
,
```
oracle
```
missing
```
.veris/config.yaml
```
env binding
assumptions that conflict with the current docs

1.2 Infrastructure files

Read and summarize any of:

docker-compose.yml

docker-compose.yaml

compose.yml

```
Dockerfile
```
,
```
Dockerfile.*
```
```
Procfile
```
```
supervisord.conf
```
,
```
supervisord.ini
```
```
vercel.json
```
,
```
serverless.yml
```
,
```
netlify.toml
```
Kubernetes manifests

Identify:

which process is the user-facing agent
what other services exist
how the system currently starts

1.3 Environment and secrets

Read:

```
.env.example
```
,
```
.env.sample
```
,
```
.env.template
```
config/settings modules
secret or vault references

Collect every env var the agent reads, and note which are:

stable non-secrets
secrets
service endpoints
optional or debug-only

1.4 Dependencies

Read the package manifests for the repo’s language/runtime and identify:

package manager
framework
Python/Node runtime assumptions
SDKs for external services

1.5 Source-code entrypoints

Find the actual code path that handles incoming user work:

app/server entrypoint
chat/message handler
config/settings module
request routing
any background worker or webhook listener that matters during a user conversation

1.5a Platform-hosted agents (config-only repos)

If the repo has no traditional application entrypoint — no

main.py

app.py

server.js

index.ts

— check whether it is a platform-hosted agent: a repo of config files that runs on an installed framework (CrewAI, LangServe, AutoGen, Dify, n8n, Flowise, or similar).

Signs:

Primary files are YAML/JSON config, prompt templates, and tool definitions
```
pyproject.toml
```
or
```
package.json
```
lists a framework as the main dependency
No substantial application logic beyond small tool/hook files
README instructions say "install [framework], then run [framework command]"

If this is the case:

The framework is the runtime — it will be installed in the Dockerfile, not built from source
The entry point is the framework's CLI or server command
See Pattern 8 in
```
reference/infrastructure-patterns.md
```
for the full restructuring approach
Watch for source-tree compile errors if you attempt
```
pip install .
```
on these repos

1.6 Determine the integration interface

This is critical. Determine how the simulated actor should talk to the agent.

Look for four classes of interfaces:

HTTP

Chat endpoint
Request/response body shape
Session or conversation field
JSON or SSE response style

WebSocket

WS route
Message framing
Session handling

Email

Inbox address
Polling or webhook flow

Function

A clean Python callable the agent already exposes as part of its public API
Existing
```
handle_message
```
-style functions the agent's own documentation treats as an entry point

Do not invent a function interface by wrapping a CLI or a server. If the agent is CLI-only in production, the integration is CLI-driven — surface that and find the right Veris channel for it, or log it as a platform gap. A function channel is only correct when the repo already ships a callable as its primary or documented interface.

If both network and function modes are viable, use the repo's real product interface. That is what runs in production; that is what we test.

Tell the user exactly what you found and confirm the likely best integration path before continuing.

Proceed to Phase 2.

Phase 2: Analyze Dependencies And Service Strategy

[Phase 2/7]

Tell the user: "I'm now classifying each dependency into mock, bundle, external, or skip."

Read:

reference/service-mapping.md
reference/env-var-overrides.md
reference/bundling-recipes.md

For every dependency, classify it as one of:

Mock with Veris
Bundle inside the container
Use an external endpoint
Skip entirely
Needs discussion
Allow real egress — the agent must reach the real internet (e.g., web search, URL scraping, live API with no mock). Results will be nondeterministic across simulation runs.

Classification rules

Always read the source code before deciding. Do not infer importance from service names alone.
Show evidence when you decide something is skippable.
Surface bundle cost when it matters, especially for heavy services like Elasticsearch or LocalStack.
Prefer mock services when the dependency maps cleanly to Veris.
Prefer env-var overrides over code changes whenever possible.

Special cases

Postgres

Decide whether to use Veris
```
postgres
```
or an external DB
If using Veris
```
postgres
```
, find the schema artifact or migration source and determine the best copy path

LLM providers

No Veris service entry is needed
The LLM proxy intercepts supported domains automatically

Email

If the actor uses an email channel, note that the Veris email service is injected automatically

Auth helpers

Google/Microsoft/Atlassian/Intuit auth helpers are platform-level helpers, not services you should normally add manually

Web search and scraping

If the agent calls search APIs (Google, Bing, SerpAPI, Tavily, Brave Search, DuckDuckGo) or fetches live URLs, these cannot be mocked
Classify as "Allow real egress"
Warn the user: live internet calls make simulation results nondeterministic — the same scenario may produce different outputs on different runs
If the search is truly optional (e.g., a fallback when the knowledge base has no answer), consider disabling it via env var for deterministic simulations

Real internet egress (general)

Some agents need to hit arbitrary external endpoints that Veris cannot mock (webhooks to third-party services, real-time data feeds, public REST APIs without a Veris service)
These also classify as "Allow real egress"
The Veris container allows outbound internet by default for non-intercepted domains
Surface the nondeterminism tradeoff to the user

Checkpoint

Walk through your dependency analysis with the user before moving on. The user should understand:

what will be mocked
what will be bundled
what stays external
what gets skipped
what still needs a decision

Wait for approval before proceeding.

Phase 3: Choose Integration Mode And Container Architecture

[Phase 3/7]

Tell the user: "I'm locking down how this agent will run inside the Veris container and how the actor will talk to it."

Read reference/infrastructure-patterns.md.

3.1 Choose the channel strategy

Pick one of:

HTTP — preferred when the product is already an HTTP chat API
WebSocket — preferred when real-time stateful messaging is core
Email — preferred when the product is genuinely email-driven
Function — preferred when the repo has a clean callable path or should be treated as a one-shot request/response agent

3.2 Function-channel rules

If you choose a function channel:

The callable path must be something the agent repo already exposes as a public interface (documented, referenced in its README, or otherwise part of its contract)
Do not create a wrapper file to conjure a callable out of a CLI or server — if the repo doesn't already expose one, function is the wrong channel
Omit
```
agent.entry_point
```
and
```
agent.port
```
in
```
veris.yaml
```
If the callable is one-shot and stateless, set
```
actor.config.MAX_TURNS: 1
```

3.3 Network-channel rules

If you choose HTTP / WS / email:

determine the exact request and response mappings
determine the startup command
choose a non-reserved port
decide whether
```
start.sh
```
is needed for bundled infra or multiple processes

3.4 Container layout

Determine:

what gets copied into
```
/agent
```
which files should stay out of the image
whether a
```
start.sh
```
is required to bundle multiple processes (this is container orchestration, not agent modification)

Do not plan "which code changes are necessary." The target is zero code changes to the agent. If an env-var override isn't enough and the agent genuinely can't run as-shipped, that's a finding — escalate it rather than patching the source.

Checkpoint

Explain:

how the actor will communicate with the agent (using the agent's real production interface)
how the agent will start inside the container (its real production start command)
what files will be copied

If you believe any agent-side code change is needed, flag it here and stop. The default answer is zero code changes. If you can't see a way forward without one, it's probably a Veris platform gap, not an integration step.

Wait for approval before proceeding.

Phase 4: Generate

.veris/veris.yaml

[Phase 4/7]

Tell the user: "I'm generating the final Veris configuration in the current preferred schema."

Read:

reference/veris-yaml-schema.md
templates/veris-yaml.md

Rules

Use
```
actor.channels
```
, not
```
persona.modality
```
Use canonical service names from
```
reference/service-mapping.md
```
Use
```
agent_inbox
```
, not
```
email_address
```
Only set
```
actor.config.MAX_TURNS
```
when there is a concrete reason, usually a one-shot function integration
Do not add the
```
*_INTERVAL
```
knobs unless the user explicitly asks for advanced tuning
Keep secrets out of
```
veris.yaml
```
Put stable non-secret defaults in
```
agent.environment
```
Only use
```
${VAR}
```
in
```
agent.environment
```
when you need expansion/composition; if the agent can read a runtime env var directly, prefer setting it with
```
veris env vars set
```

Channel-specific rules

HTTP / WS / Email

include
```
agent.code_path
```
include
```
agent.entry_point
```
include
```
agent.port
```

Function

include
```
agent.code_path
```
omit
```
agent.entry_point
```
omit
```
agent.port
```
set
```
actor.channels[0].type: function
```
set
```
callable: ...
```

Checkpoint

Show the complete

veris.yaml

, explain the sections, and get approval before writing or finalizing it.

Phase 5: Generate

.veris/Dockerfile.sandbox

And Supporting Files

[Phase 5/7]

Tell the user: "I'm generating the image build and any small support files needed for this integration."

Read:

templates/dockerfile-sandbox.md
templates/start-sh.md

5.1 Dockerfile rules

Start with:

dockerfile

ARG GVISOR_BASE
FROM ${GVISOR_BASE}

Build context is the repo root
Copy dependency manifests before source code
Copy only what the agent actually needs
End with
```
WORKDIR /app
```
Do not bake
```
veris.yaml
```
into the image

5.2 Runtime notes

The current base image already includes Python,
```
uv
```
, and Node.js
Only install extra runtimes or system packages when the repo truly needs them
If using a function channel, you still package the agent code and dependencies normally; you just do not start a network server

5.3 Supporting files

Create only what is needed:

```
start.sh
```
for bundling multiple processes (e.g., a database alongside the agent) — this is container orchestration, same as a
```
docker-compose.yaml
```
would be
```
.veris/.dockerignore
```
updates if the repo has large directories the default ignore file misses

Do not create Python "wrapper modules" that expose the agent as a callable, translate Veris actor calls into the agent's native format, or otherwise insert themselves between the actor and the agent. Use the agent's real interface.

5.4 No code changes to the agent

The agent runs in Veris exactly as it runs in production. That means:

No source-code patches to accommodate simulation
No "simulation mode" flags or Veris-specific branches
No forked copies of the agent with local modifications

If you find yourself wanting to change the agent's source, stop. Either:

The change can be expressed as an env-var override (then do it that way, via
```
agent.environment
```
or
```
veris env vars set
```
), or
The change is a real issue in the agent (then it's the customer's responsibility to fix, and it would also affect production), or
Veris can't accommodate the agent as-shipped (then it's a platform gap — escalate)

Unrelated refactors are obviously out.

Proceed directly to Phase 6 once the files are in place.

Phase 6: Configure Runtime Env Vars, Validate, And Push

[Phase 6/7]

Tell the user: "I'm turning this into a pushable Veris environment."

Read:

templates/env-vars.md
phases/troubleshooting.md

6.1 Build the env-var plan

Classify env vars into:

Stable non-secret defaults → put in
```
agent.environment
```
Secrets / per-environment values → set with
```
veris env vars set
```
Local-only convenience values → optional root
```
.env
```
or shell exports for local smoke tests

Do not create

.env.simulation

6.2 Produce exact commands

Generate the exact

veris env vars set

commands the user needs.

If the user provides actual values and wants you to do it, run the commands for them.

Shell interpolation pitfall: when running

veris env vars set KEY="$VAR" --secret

with a shell variable, verify the source variable is actually set first (

printenv VAR

test -n "$VAR"

). An empty or unset variable expands to

""

silently — the CLI will happily save an empty secret with no error, and the agent will fail at runtime with a confusing auth/provider error instead of a clear "missing key" message.

6.3 Validate push preconditions

Before pushing, verify:

```
veris
```
is installed
auth/profile works
```
.veris/config.yaml
```
has an environment ID
```
.veris/veris.yaml
```
exists
```
.veris/Dockerfile.sandbox
```
exists

Optional but encouraged:

run a local
```
docker build -f .veris/Dockerfile.sandbox .
```
smoke test when that is likely to catch obvious breakage quickly

6.4 Push

If the user approves, run:

bash

veris env push

Or with an explicit tag if the user wants one:

bash

veris env push --tag <tag>

If the push fails:

diagnose the failing build step
fix the integration
retry

6.5 Final summary

Summarize:

files created or modified
integration mode chosen
services mocked, bundled, external, or skipped
env vars set vs left for the user
whether
```
veris env push
```
succeeded and which tag was created

Then suggest the next commands:

```
veris scenarios create
```
```
veris simulations create
```

Phase 7: Smoke Validation

[Phase 7/7]

Tell the user: "I'm going to run a single scenario and simulation to verify the integration works end-to-end."

7.1 Create a smoke scenario

bash

veris scenarios create --num 1

The goal is a single short interaction that exercises the agent's primary interface.

7.2 Run a single simulation

bash

veris simulations create --scenario-set-id <id>

Wait for it to complete.

7.3 Check the results

Review the simulation for:

Agent responded with real content — not an error page, empty body, or exception traceback
Mock services were called — if the agent should call Slack, Salesforce, etc., confirm those calls appear
No startup crashes — the agent process stayed alive for the duration
Channel contract is correct — the actor's messages reached the agent and responses came back in the expected shape

7.4 Diagnose failures

If the smoke test fails:

Check agent container logs for startup errors or missing env vars
Verify
```
actor.channels
```
request/response mapping matches the actual API shape
Confirm mock service credentials and DNS aliases are correct
Return to the relevant phase to fix and re-push

7.5 Sign off

If the smoke test passes, summarize:

What the actor sent and what the agent responded
Which services were exercised
Confidence level that the integration is ready for full scenario generation

Then suggest full scenario generation (

veris scenarios create --num N

) and simulation as the next step.

Practical guidance

Prefer current conventions over stale scaffolding

veris env create

scaffolds old-looking placeholders, overwrite them with the current preferred shape from this skill.

Keep the skill honest about function channels

Use a function channel only when the agent already exposes a callable as part of its public interface. Do not force a networked product into a function callable just because it seems simpler, and never create a wrapper file to invent a callable the agent doesn't already have.

Keep the skill honest about one-shot agents

If the integrated agent is clearly one-shot/stateless, carry that through explicitly by setting

actor.config.MAX_TURNS: 1

Be explicit about what you did not automate

If login, secrets, or env-var values still require user action, say so plainly. The goal is to get as far as possible, not to hide blockers.

agent-integration

NPX Install

Tags

SKILL.md Content

Core framing: the agent is the constant, Veris is the test harness

Core rules

Fast-track mode

Read these files when needed

Workflow Overview

Phase 0: Bootstrap Veris Tooling And Environment

0.1 Verify repo root

0.2 Verify veris-cli

0.3 Verify Veris authentication

0.4 Verify or create .veris/

0.5 Treat scaffolding as placeholders, not truth

Phase 1: Discover The Repo And Current Runtime

1.1 Existing Veris state

1.2 Infrastructure files

1.3 Environment and secrets

1.4 Dependencies

1.5 Source-code entrypoints

1.5a Platform-hosted agents (config-only repos)

1.6 Determine the integration interface

Phase 2: Analyze Dependencies And Service Strategy

Classification rules

Special cases

Checkpoint

Phase 3: Choose Integration Mode And Container Architecture

3.1 Choose the channel strategy

3.2 Function-channel rules

3.3 Network-channel rules

3.4 Container layout

Checkpoint

Phase 4: Generate .veris/veris.yaml

Rules

Channel-specific rules

Checkpoint

Phase 5: Generate .veris/Dockerfile.sandbox And Supporting Files

5.1 Dockerfile rules

5.2 Runtime notes

5.3 Supporting files

5.4 No code changes to the agent

Phase 6: Configure Runtime Env Vars, Validate, And Push

6.1 Build the env-var plan

6.2 Produce exact commands

6.3 Validate push preconditions

6.4 Push

6.5 Final summary

Phase 7: Smoke Validation

7.1 Create a smoke scenario

7.2 Run a single simulation

7.3 Check the results

7.4 Diagnose failures

7.5 Sign off

Practical guidance

Prefer current conventions over stale scaffolding

Keep the skill honest about function channels

Keep the skill honest about one-shot agents

Be explicit about what you did not automate

0.2 Verify
`veris-cli`

0.4 Verify or create
`.veris/`

Phase 4: Generate
`.veris/veris.yaml`

Phase 5: Generate
`.veris/Dockerfile.sandbox`
And Supporting Files