Agent Integration

interface:
  display_name: "Agent Integration"
  short_description: "Integrate a raw repo with Veris end to end"
  default_prompt: "Use $agent-integration to make this agent repo Veris-ready from scratch and push it with veris env push."

policy:
  allow_implicit_invocation: true


# Troubleshooting

Common integration issues organized by symptom.

## `veris-cli` bootstrap problems

### `veris` command not found

Install the CLI first:

```bash
uv tool install veris-cli
```

Fallback:

```bash
pip install veris-cli
```

### `veris env push` says no environment is configured

The repo is missing `.veris/config.yaml` with an environment binding. Run:

```bash
veris env create --self-serve --name "<env-name>"
```

Use `--self-serve` for this skill's flow; plain `veris env create` can place the env in managed onboarding and block `veris env push` with a 409.

### Auth problems

If the CLI is installed but backend calls fail, the user likely needs:

```bash
veris login
```

Or API-key login for headless contexts.

## Agent fails to start

Common causes:

1. Missing required env var
2. Wrong `entry_point`
3. Wrong `code_path`
4. Missing dependency install in `Dockerfile.sandbox`
5. Bundled service not started before the agent

Check the agent logs first. The startup error usually points directly at the missing dependency or bad command.

## Actor cannot reach the agent

For HTTP / WS / email integrations:

1. `actor.channels[].url` points at the wrong port or path
2. `agent.port` does not match the server’s listen port
3. The agent binds only to `127.0.0.1` instead of `0.0.0.0`
4. The server takes too long to become healthy

For function integrations:

1. `callable` import path is wrong
2. Wrapper file was not copied into `/agent`
3. The callable returns a shape the driver cannot serialize cleanly

## Agent runs but cannot reach mocked services

Common causes:

1. Missing or wrong `services:` entry
2. Wrong `dns_aliases`
3. Wrong env-var override, especially old docker-compose hostnames that should be `localhost`
4. Missing mock credentials

Check `reference/service-mapping.md` and `reference/env-var-overrides.md`.

## Grader flags a voice agent for hallucinating tools it actually called

Symptom: a `voice_ws` / phone agent runs its tools correctly (the agent logs, and any mock-service logs, show the calls happening and the database changing), but the grader reports "no tool call," "fabricated," or "claimed an action without calling the tool."

Cause: the agent uses **client tools** (ElevenLabs Conversational AI, OpenAI Realtime, Gemini Live, …) that execute in-process and round-trip on the vendor WebSocket, so they never reach the spoken transcript the voice grader reads. Without an explicit report, the grader is blind to them. This is a grading-visibility issue, not an agent bug — the actions really happened.

Fix: emit an `agent_tool_call` event per tool call — see [reference/voice-channels.md](../reference/voice-channels.md#making-client-tool-calls-visible-to-the-grader) for the contract and copy-paste hook. If you already added the hook and still see this, check:

1. `event_type` is exactly `agent_tool_call`, and `data.name` / `data.arguments` are present (the renderer needs both).
2. `SIMULATION_ID` is set in the agent process — it's exported by the sandbox; if your hook silently no-ops, it isn't reading the env you think it is.
3. The POST is actually landing — a swallowed connection error logs `could not report <tool> to engine`. Confirm `ENGINE_URL` (default `http://localhost:6100`) is reachable from the agent.

## Database connection fails

Common causes:

1. Old docker hostname (`postgres`, `db`) instead of `localhost`
2. Password mismatch between `services[].config.POSTGRES_PASSWORD` and `DATABASE_URL`
3. Schema file copied to the wrong path
4. Wrong database name instead of `SIMULATION_ID`

## Bundled service fails

Common causes:

1. Service package not installed in `Dockerfile.sandbox`
2. Service not started or not he