fix(cli): load the agent's .env into locally run ACP and worker processes

[michaelxu2288]

Problem

getting_started/project_structure.md says a .env next to manifest.yaml "is automatically loaded when placed alongside your manifest.yaml file, but only for local development". Nothing does that today:

• agentex agents run builds the child environment from os.environ plus the manifest (create_agent_environment).
• EnvironmentVariables.refresh() loads .env from Path(__file__).parents[2], which is site-packages for an installed SDK, never the agent folder, and .env.local from cwd.parent.
• ProjectConfigLoader._load_env only feeds config templating.

Values from .env reach a process only when some import happens to call load_dotenv() first. litellm does, on import (litellm/__init__.py), which is why the Temporal + OpenAI Agents template appears to work (its model client is built lazily inside the activity, after imports) while Temporal + Pydantic AI fails at import time of project/agent.py with openai.OpenAIError: Missing credentials. Verified with a print at the top of both workers: OpenAI Agents worker sees LITELLM_API_KEY only after its imports; the Pydantic AI worker never does.

Fix

create_agent_environment(manifest, manifest_dir) merges <manifest dir>/.env (python-dotenv dotenv_values, already a dependency) into the environment handed to both the ACP and worker subprocesses, without overriding variables already set in the shell (python-dotenv semantics). run_agent passes manifest_file.parent. 16-line diff plus three tests (merge, shell precedence, no file / no manifest_dir) that render a real manifest via the init helpers.

Verification

• tests/lib/cli/test_run_handlers_env.py: 3 passed; streaming handler tests still pass; ruff clean.
• Live, Temporal + Pydantic AI scaffold with only LITELLM_API_KEY in .env, patched SDK installed into its venv: before, no reply and Missing credentials; after, reply in 4.7 s, zero worker errors.

Pairs with #514 ("fix(templates): map LITELLM_API_KEY to OPENAI_API_KEY in Temporal workers"): once .env is in the process environment from the start, that mapping at the top of run_worker.py becomes deterministic instead of depending on import order.

https://claude.ai/code/session_01HCVKnA7LeJZ44nxZz1uzF3

Confidence Score: 4/5

The PR is not yet safe to merge because .env can override runtime identity, port, or workflow settings derived from the manifest.

Findings

1.  Dotenv overrides manifest settings ▶
2.  Dotenv defaults are overwritten ▶

Fix with agent prompt

### Issue 1
src/agentex/lib/cli/handlers/run_handlers.py:476-478
A `.env` entry can now overwrite manifest-derived runtime settings such as `AGENT_NAME`, `ACP_PORT`, `WORKFLOW_TASK_QUEUE`, and `HEALTH_CHECK_PORT`. These values are added through `env_vars`, but `manifest_env` contains only the explicit `agent.env` mapping. A conflicting dotenv value therefore replaces the manifest-derived value and can start the ACP or worker with the wrong identity, port, task queue, or health-check configuration. Preserve all manifest-derived keys while still allowing `.env` to replace built-in local defaults.

### Issue 2
src/agentex/lib/cli/handlers/run_handlers.py:423-425
The `.env` values are loaded before `env_vars` is built, and the later unconditional `env.update(env_vars)` replaces overlapping values. For example, a local Temporal project with `REDIS_URL=redis://custom:6380` in `.env` still receives `redis://localhost:6379`. This makes the new loading behavior ineffective for common runtime settings such as `REDIS_URL`, `TEMPORAL_ADDRESS`, and `ENVIRONMENT`. Please apply dotenv values after the built-in defaults while preserving the intended shell and manifest precedence, and add a regression test for an overlapping key.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

• Passes the manifest directory into subprocess environment construction.
• Loads dotenv values without replacing exported shell variables or explicit agent.env entries.
• Keeps ENVIRONMENT fixed to development.
• Adds focused tests for dotenv loading, shell precedence, missing files, and local-default overrides.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  S[Shell environment] --> M[Apply manifest-derived settings]
  M --> D[Apply eligible .env values]
  D --> E[Child process environment]
  E --> A[ACP process]
  E --> W[Temporal worker]

Loading

_{Reviews (2) · Last reviewed commit: "fix(cli): apply .env after the built-in ..."}

[greptile-apps]

Dotenv defaults are overwritten

The .env values are loaded before env_vars is built, and the later unconditional env.update(env_vars) replaces overlapping values. For example, a local Temporal project with REDIS_URL=redis://custom:6380 in .env still receives redis://localhost:6379. This makes the new loading behavior ineffective for common runtime settings such as REDIS_URL, TEMPORAL_ADDRESS, and ENVIRONMENT. Please apply dotenv values after the built-in defaults while preserving the intended shell and manifest precedence, and add a regression test for an overlapping key.

Knowledge Base Used: Command-line workflows

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agentex/lib/cli/handlers/run_handlers.py
Line: 423-425

Comment:
**Dotenv defaults are overwritten**

The `.env` values are loaded before `env_vars` is built, and the later unconditional `env.update(env_vars)` replaces overlapping values. For example, a local Temporal project with `REDIS_URL=redis://custom:6380` in `.env` still receives `redis://localhost:6379`. This makes the new loading behavior ineffective for common runtime settings such as `REDIS_URL`, `TEMPORAL_ADDRESS`, and `ENVIRONMENT`. Please apply dotenv values after the built-in defaults while preserving the intended shell and manifest precedence, and add a regression test for an overlapping key.

**Knowledge Base Used:** [Command-line workflows](https://app.greptile.com/scale-ai/-/custom-context/knowledge-base/scaleapi/scale-agentex-python/-/docs/command-line-workflows.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[michaelxu2288]

Good catch. Pushed 0a24841: .env is now applied after the built-in local defaults, so a custom REDIS_URL or TEMPORAL_ADDRESS in .env takes effect, while the manifest's env block and variables already set in the shell still win, and ENVIRONMENT stays pinned to development (that is what makes it a local run). Added test_dotenv_overrides_builtin_local_defaults_but_not_environment covering exactly the overlapping-key case; the four env tests pass.

[greptile-apps]

Dotenv overrides manifest settings

A .env entry can now overwrite manifest-derived runtime settings such as AGENT_NAME, ACP_PORT, WORKFLOW_TASK_QUEUE, and HEALTH_CHECK_PORT. These values are added through env_vars, but manifest_env contains only the explicit agent.env mapping. A conflicting dotenv value therefore replaces the manifest-derived value and can start the ACP or worker with the wrong identity, port, task queue, or health-check configuration. Preserve all manifest-derived keys while still allowing .env to replace built-in local defaults.

Knowledge Base Used: Command-line workflows

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agentex/lib/cli/handlers/run_handlers.py
Line: 476-478

Comment:
**Dotenv overrides manifest settings**

A `.env` entry can now overwrite manifest-derived runtime settings such as `AGENT_NAME`, `ACP_PORT`, `WORKFLOW_TASK_QUEUE`, and `HEALTH_CHECK_PORT`. These values are added through `env_vars`, but `manifest_env` contains only the explicit `agent.env` mapping. A conflicting dotenv value therefore replaces the manifest-derived value and can start the ACP or worker with the wrong identity, port, task queue, or health-check configuration. Preserve all manifest-derived keys while still allowing `.env` to replace built-in local defaults.

**Knowledge Base Used:** [Command-line workflows](https://app.greptile.com/scale-ai/-/custom-context/knowledge-base/scaleapi/scale-agentex-python/-/docs/command-line-workflows.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.