Agent Workflow Kit

The Envy Agent Workflow Kit provides guidelines, prompt instructions, and reusable skills so AI coding agents can work autonomously with Kubernetes preview environments.

---

The Autonomous Verification Loop

Build, verify, and iterate

The agent supplies an image, creates or updates a composition, and waits for readiness before testing its URL. Failed tests lead to log inspection and another image revision. After the final test, request teardown and report the outcome.

Agent / externalEnvy / routing

Scroll sideways to follow wider branches, or read the connections below.

Read the connections

• Build an image → Create or update: published image.
• Create or update → Wait for readiness: composition id.
• Wait for readiness → Test the preview URL: ready url.
• Test the preview URL → Inspect logs & fix: checks fail.
• Inspect logs & fix → Build an image: build a new revision.
• Test the preview URL → Destroy & report: testing complete.

---

What the agent tests

The ready URL enters the same service graph shown on the homepage. MCP manages the composition; the agent’s HTTP client or browser sends the application requests.

One application, two request paths

Both URLs reuse gateway and service-a. The selected mesh selects service-b v2 only when the request carries the matching composition ID. Both service-b versions connect to the same shared data.

Envy / routingPreview overrideShared baseline

Scroll sideways to follow wider branches, or read the connections below.

Read the connections

• Baseline URL → gateway · v1: baseline request.
• Preview URL → gateway · v1: preview request.
• gateway · v1 → service-a · v1: forward baggage.
• service-a · v1 → service-b · v1: no matching context.
• service-a · v1 → service-b · v2: composition=cmp-123.
• service-b · v1 → Database & cache: read / write.
• service-b · v2 → Database & cache: read / write.

Adding Instructions to Application Repositories

Envy provides an AGENTS.md template designed to be placed in each application repository. This file teaches coding agents how to interact with Envy:

# Agent Instructions for Envy Preview Environments

## Pre-Requisites

- The Envy MCP server is configured via your IDE or CLI environment.
- Always inspect approved components before attempting an override.

## Workflow Rules

1. Decide whether a running preview is needed. Reuse an explicitly associated
   preview when suitable; inspect its generation and expiry. Call `list_components`
   for project `shop` before creating an override and select exact published builds
   when available. Use `overrides={}` when the complete baseline is sufficient.
2. When creating a composition, use an explicit `name` indicating your task.
   Select the approved deployed reference baseline for the project; the local
   demo calls its fixture `staging`:
   `create_composition(project="shop", baseline="staging", name="agent-<task>", overrides={...})`
3. Always wait for readiness using `wait_for_composition` before making HTTP calls.
4. If requests return 500 or timeout:
   - Call `get_component_logs(id=..., component=...)`
   - Read the stack trace, fix the issue, and call `update_composition`
5. Send the complete desired override set on updates, including earlier changes
   you need to retain. Updates keep the URL and do not renew TTL. Choose message
   isolation explicitly at creation for an onboarded Pub/Sub application.
6. Destroy disposable previews after verification. If the user requested a review
   environment, report its URL and expiry and retain it for that purpose.

---

Self-Healing and Log Inspection Pattern

When an AI agent introduces a bug (such as an unhandled nil pointer exception or database connection timeout), standard CI reports a generic red build.

With Envy, the agent can diagnose the issue directly:

1. Test Failure:

   GET http://cmp-7f39a.envy.localhost:8080/checkout
   HTTP 500 Internal Server Error

2. Agent Calls get_component_logs:

   {
     "id": "cmp-7f39a",
     "component": "service-b",
     "tail_lines": 50
   }

3. Log Diagnostic:

   panic: runtime error: invalid memory address or nil pointer dereference
   goroutine 18 [running]:
   github.com/org/service-b/internal/handler.HandleCheckout(...)
       /app/internal/handler/checkout.go:42 +0x3a

4. Self-Healing Update: The agent modifies checkout.go, builds a new image tag, and calls update_composition(id=..., expected_generation=1, ...). The preview updates in place without losing its URL.

---

After every image update, wait for readiness again before rerunning tests. Fetch the current generation before updating rather than assuming it is still 1.

Recipe Export and Recreation

Agents can serialize complex multi-override environments into portable recipes:

envy recipe export cmp-7f39a > recipe.json

Another agent or team member can recreate the saved override configuration later. Recipes do not snapshot shared databases or external dependencies:

envy recipe validate --file recipe.json
envy recipe recreate --file recipe.json \
  --name agent-recreated \
  --idempotency-key recipe-cmp-7f39a