[AGX1-98] Change standard ports to non-standard and make configurable

[danielmillerp]

Summary

• Migrated AgentEx default ports from generic/common ports to less commonly used ports to avoid conflicts:
  • AgentEx API: 5003 → 5718
  • ACP Server: 8000 → 8718
  • Health Check: 80 → 8080
  • Multi-agent examples: 8000-8003 → 8718-8721
• Centralized all port defaults in src/agentex/lib/constants/ports.py
• Updated ~150 files: core SDK, CLI templates, 22+ Dockerfiles, 21+ manifests, 39 test files, 25 notebooks, READMEs, and example scripts
• All ports remain configurable via environment variables (AGENTEX_BASE_URL, ACP_PORT, HEALTH_CHECK_PORT) and manifest configuration

Test plan

• Verify ruff check and ruff format pass on modified source files
• Run rye run pytest to verify existing tests pass with new port defaults
• Test agentex agents run --manifest manifest.yaml with a tutorial to verify local dev works
• Verify multi-agent example starts correctly with new ports (8718-8721)
• Confirm environment variable overrides still work (e.g., ACP_PORT=9000)

Note: .github/workflows/*.yml changes excluded from this PR (requires workflow scope token). The CI workflow already has the updated ports.

🤖 Generated with Claude Code

[greptile-apps]

_{69 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Shell form CMD changes signal handling

Switching from exec form (CMD ["uvicorn", ...]) to shell form (CMD uvicorn ...) is needed for ${ACP_PORT} env var expansion, but it means the container process runs under /bin/sh -c, not as PID 1 directly. This means SIGTERM from docker stop goes to the shell, not uvicorn, which can cause a 10-second timeout before a SIGKILL during container shutdown.

Consider using exec form with shell expansion via ENTRYPOINT:

ENV ACP_PORT=8718
CMD ["sh", "-c", "exec uvicorn project.acp:acp --host 0.0.0.0 --port ${ACP_PORT}"]

The exec replaces the shell with uvicorn as PID 1, preserving proper signal handling. This same pattern applies to all 14 Dockerfile templates changed in this PR.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agentex/lib/cli/templates/default/Dockerfile.j2
Line: 42-43

Comment:
**Shell form CMD changes signal handling**

Switching from exec form (`CMD ["uvicorn", ...]`) to shell form (`CMD uvicorn ...`) is needed for `${ACP_PORT}` env var expansion, but it means the container process runs under `/bin/sh -c`, not as PID 1 directly. This means `SIGTERM` from `docker stop` goes to the shell, not uvicorn, which can cause a 10-second timeout before a `SIGKILL` during container shutdown.

Consider using exec form with shell expansion via `ENTRYPOINT`:
```dockerfile
ENV ACP_PORT=8718
CMD ["sh", "-c", "exec uvicorn project.acp:acp --host 0.0.0.0 --port ${ACP_PORT}"]
```

The `exec` replaces the shell with uvicorn as PID 1, preserving proper signal handling. This same pattern applies to all 14 Dockerfile templates changed in this PR.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

_{94 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Old debug port in sibling acp.py not updated

While the Dockerfile and manifest in this directory were correctly updated, examples/demos/procurement_agent/project/acp.py:19 still contains os.getenv("AGENTEX_DEBUG_PORT", "5679") — using the old default. The same applies to 6 other example acp.py files under examples/tutorials/10_async/10_temporal/:

• 030_custom_activities/project/acp.py:8
• 060_open_ai_agents_sdk_hello_world/project/acp.py:10
• 070_open_ai_agents_sdk_tools/project/acp.py:10
• 080_open_ai_agents_sdk_human_in_the_loop/project/acp.py:10
• 090_claude_agents_sdk_mvp/project/acp.py:12
• 100_gemini_litellm/project/acp.py:10

These should all be updated from "5679" to "9679" to stay consistent with the new DEFAULT_ACP_DEBUG_PORT.

Prompt To Fix With AI

This is a comment left during a code review.
Path: examples/demos/procurement_agent/Dockerfile
Line: 45

Comment:
**Old debug port in sibling acp.py not updated**

While the Dockerfile and manifest in this directory were correctly updated, `examples/demos/procurement_agent/project/acp.py:19` still contains `os.getenv("AGENTEX_DEBUG_PORT", "5679")` — using the old default. The same applies to 6 other example `acp.py` files under `examples/tutorials/10_async/10_temporal/`:

- `030_custom_activities/project/acp.py:8`
- `060_open_ai_agents_sdk_hello_world/project/acp.py:10`
- `070_open_ai_agents_sdk_tools/project/acp.py:10`
- `080_open_ai_agents_sdk_human_in_the_loop/project/acp.py:10`
- `090_claude_agents_sdk_mvp/project/acp.py:12`
- `100_gemini_litellm/project/acp.py:10`

These should all be updated from `"5679"` to `"9679"` to stay consistent with the new `DEFAULT_ACP_DEBUG_PORT`.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Additional Comments (1)

src/agentex/lib/cli/templates/temporal/project/acp.py.j2
Missed port migration in template

This template still uses the old default debug port "5679". Since this PR migrates the ACP debug port from 5679 → 9679 (defined as DEFAULT_ACP_DEBUG_PORT in environment_variables.py), this fallback should be updated to match. The same issue exists in src/agentex/lib/cli/templates/temporal-openai-agents/project/acp.py.j2:17.

New projects scaffolded from these templates will get the old port default, creating an inconsistency with the rest of the SDK.

        debug_port = int(os.getenv("AGENTEX_DEBUG_PORT", "9679"))

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agentex/lib/cli/templates/temporal/project/acp.py.j2
Line: 11

Comment:
**Missed port migration in template**

This template still uses the old default debug port `"5679"`. Since this PR migrates the ACP debug port from `5679` → `9679` (defined as `DEFAULT_ACP_DEBUG_PORT` in `environment_variables.py`), this fallback should be updated to match. The same issue exists in `src/agentex/lib/cli/templates/temporal-openai-agents/project/acp.py.j2:17`.

New projects scaffolded from these templates will get the old port default, creating an inconsistency with the rest of the SDK.

```suggestion
        debug_port = int(os.getenv("AGENTEX_DEBUG_PORT", "9679"))
```

How can I resolve this? If you propose a fix, please make it concise.

[danielmillerp]

Updated with additional commit that centralizes port defaults and improves env var configurability:

• Added centralized port constants in environment_variables.py (DEFAULT_ACP_PORT, DEFAULT_TEMPORAL_PORT, etc.)
• Fixed deploy_handlers.py to use ACP_PORT env var instead of hardcoded 8718
• Fixed cleanup_handlers.py to use TEMPORAL_ADDRESS env var instead of hardcoded localhost:7233
• Fixed run_handlers.py to respect TEMPORAL_ADDRESS and REDIS_URL env var overrides
• Fixed base_acp_server.py run() to read port from ACP_PORT env var
• Updated multi-agent start-agents.sh to support env var port overrides
• All 501 tests pass

[greptile-apps]

_{28 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Incorrect default port in description

The description says "Defaults to 9718 if not specified" but the actual default used by the system is DEFAULT_HEALTH_CHECK_PORT = 8080 (defined in src/agentex/lib/constants/ports.py:41 and consumed by EnvironmentVariables.HEALTH_CHECK_PORT in environment_variables.py:81). Port 9718 doesn't appear anywhere else in the codebase. This should be corrected to 8080.

Suggested change

	health_check_port: int | None = Field(
	default=None,
	description="Port for temporal worker health check endpoint. Defaults to 80 if not specified.",
	description="Port for temporal worker health check endpoint. Defaults to 9718 if not specified.",
	)
	health_check_port: int | None = Field(
	default=None,
	description="Port for temporal worker health check endpoint. Defaults to 8080 if not specified.",
	)

Context Used: Rule from dashboard - Constants should accurately reflect their actual values. If a constant is named 7_DAYS but contain... (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agentex/lib/types/agent_configs.py
Line: 56-59

Comment:
**Incorrect default port in description**

The description says "Defaults to 9718 if not specified" but the actual default used by the system is `DEFAULT_HEALTH_CHECK_PORT = 8080` (defined in `src/agentex/lib/constants/ports.py:41` and consumed by `EnvironmentVariables.HEALTH_CHECK_PORT` in `environment_variables.py:81`). Port 9718 doesn't appear anywhere else in the codebase. This should be corrected to `8080`.

```suggestion
    health_check_port: int | None = Field(
        default=None,
        description="Port for temporal worker health check endpoint. Defaults to 8080 if not specified.",
    )
```

**Context Used:** Rule from `dashboard` - Constants should accurately reflect their actual values. If a constant is named `7_DAYS` but contain... ([source](https://app.greptile.com/review/custom-context?memory=329791ab-6f7e-4616-9bbc-cb41f96a2d1d))

How can I resolve this? If you propose a fix, please make it concise.

[danielmillerp]

Update: Port migration across all files

Pushed commit 867674c that updates 144 files with the new non-standard ports:

• AgentEx API: 5003 → 5718
• ACP Server: 8000 → 8718
• Health Check: 80 → 8719
• Multi-agent ports: 8000-8003 → 8718-8721

Files updated:

• All example Dockerfiles, manifests, and test files
• All CLI template Dockerfiles, manifests, READMEs, and test templates
• All Jupyter notebooks (dev.ipynb)
• All tutorial test_agent.py files
• Core SDK files (environment_variables.py, deploy_handlers.py, base_acp_server.py, agent_configs.py)
• Test conftest files and worker tests
• Example scripts, READMEs, and launch scripts

Note

The CI workflow files (.github/workflows/agentex-tutorials-test.yml and build-and-push-tutorial-agent.yml) have local changes but couldn't be pushed because the PAT lacks the workflow scope. These changes update:

• HEALTH_CHECK_PORT: 8080 → 8719 in agentex-tutorials-test.yml
• ACP_URL, ACP_PORT, and port mapping 8000:8000 → 8718:8718 in build-and-push-tutorial-agent.yml

These workflow file changes need to be pushed separately with a token that has the workflow scope.

[greptile-apps]

Too many files changed for review. (150 files found, 100 file limit)