Using Artifacts with Environments

An env starts without data on every deploy. Loading artifacts into an env is how you manage its state. This page loads the artifacts from Creating your artifacts into the instances from Environments: acme-email into the email instance, and the universe acme into office.

Load an artifact into an instanceCopy Anchor Link

email-mmtflq6t, the instance from Deploying your environment, still holds the email you added by hand. This command loads acme-email into it:

agent-env env mcp-server load-environment-artifact --instance-id email-mmtflq6t \
  --environment-artifact-id acme-email

Found env: id=email version=1 environment_name=email
Fetching environment artifact: id=acme-email...
Found environment artifact: id=acme-email version=2 environment_name=email
Loading environment artifact...
Loaded environment artifact into env

The load copies the artifact's file into your server's container at /data/emails.json, calls data/reset to empty the inbox, then calls data/add with the file's path. EmailEnv's @add_data method reads the inbox and sent folder from that file.

data/get reads the state back: the three emails of version 2, without the email you added by hand:

curl -sS http://localhost:61655/agentenv -H 'content-type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "data/get"}' | python3 -m json.tool --indent 2

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "parts": [
      {
        "kind": "data",
        "data": {
          "inbox": [
            {"from": "dana@example.com", "subject": "Q3 numbers", ...},
            {"from": "priya@example.com", "subject": "Offsite", ...},
            {"from": "sam.lee@example.com", "subject": "Re: Q3 numbers", ...}
          ],
          "sent": []
        }
      }
    ]
  }
}

Each load replaces the instance's data, and the env itself stays at version 1. The command loads the latest version of the artifact; a task can pin one.

The name must matchCopy Anchor Link

The framework loads an environment artifact only into a server with the same environment name. Loading acme-contacts into the email instance stops before it copies anything:

Loading environment artifact...
Error: EnvironmentArtifact environment_name 'contacts' does not match env environment_name 'email'

The name is all it checks, so any server named email takes acme-email, whatever its env id or topology. That includes a website env, such as a webmail app that computer-use agents work in a browser, loaded with agent-env env website load-environment-artifact.

Load a universe into a composed envCopy Anchor Link

A universe loads into a multi env in one command. This one loads acme into office-jk24hzlq, the instance from Composing environments:

agent-env env multi load-environment-universe-artifact --env-instance-id office-jk24hzlq \
  --environment-universe-artifact-id acme

Instance: office-jk24hzlq (env=office v1)
Fetching environment universe artifact: id=acme...
Found environment universe artifact: id=acme version=2
Loading environment universe artifact...
[1/2] ✓ email loaded in 0s
[2/2] ✓ contacts loaded in 0s
Successfully loaded all environment artifacts into env

Each artifact goes to the child server with its environment name, and the children load in parallel. An artifact whose name no child has is skipped with a warning, so one universe fits envs that hold only some of its servers.

In a taskCopy Anchor Link

A task loads data with a load_artifact step. With env_id, it loads an environment artifact or a universe into the instance that an earlier deploy_env step started:

[
  {"id": "deploy", "type": "deploy_env", "env_id": "office", "env_version": 1},
  {
    "id": "seed",
    "type": "load_artifact",
    "env_id": "office",
    "artifact_id": "acme",
    "artifact_version": 1,
    "depends_on": [{"task_step_id": "deploy"}]
  }
]

Pinned to version 1, this task loads the two-email inbox on every run, even after acme version 2 exists. Without artifact_version, each run loads the latest version.