diff --git a/sdk/guides/agent-acp.mdx b/sdk/guides/agent-acp.mdx
index b4ac3ca0..810c977d 100644
--- a/sdk/guides/agent-acp.mdx
+++ b/sdk/guides/agent-acp.mdx
@@ -78,9 +78,9 @@ Each `AgentContext` field is tagged as ACP-compatible or not. At initialization,
 | `load_user_skills` | ✅ | Load skills from `~/.openhands/skills/` |
 | `load_public_skills` | ✅ | Load skills from the public extensions repo |
 | `marketplace_path` | ✅ | Filter public skills via marketplace JSON |
-| `secrets` | ❌ | ACP subprocesses do not use OpenHands secret injection |
+| `secrets` | ✅ | Injected into the ACP subprocess environment (and masked if the server echoes them back) |
 
-Passing `secrets` (or any future field marked `acp_compatible: False`) raises `NotImplementedError`.
+Any `AgentContext` field marked `acp_compatible: False` raises `NotImplementedError` at initialization.
 
 ### What ACPAgent Does Not Support
 
@@ -124,7 +124,6 @@ If you attach to an existing conversation by `conversation_id`, use `ACPAgent` f
 agent = ACPAgent(
     acp_command=["npx", "-y", "@agentclientprotocol/claude-agent-acp"],
     acp_args=["--profile", "my-profile"],      # extra CLI args
-    acp_env={"ANTHROPIC_API_KEY": "sk-..."},   # extra env vars
 )
 ```
 
@@ -132,7 +131,23 @@ agent = ACPAgent(
 |-----------|-------------|
 | `acp_command` | Command to start the ACP server (required) |
 | `acp_args` | Additional arguments appended to the command |
-| `acp_env` | Additional environment variables for the server process |
+| `acp_env` | **Deprecated** (removed in 1.29.0). Route env/credentials through the conversation's `secrets` or `agent_context.secrets` instead — see below. |
+
+### Environment Variables and Credentials
+
+Pass the environment variables and credentials the ACP server needs through the conversation's `secrets` (or `agent_context.secrets`). They flow into the conversation's secret registry, are injected into the ACP subprocess environment, and are masked if the server echoes them back into its output:
+
+```python icon="python"
+conversation = Conversation(
+    agent=agent,
+    workspace="./my-project",
+    secrets={"ANTHROPIC_API_KEY": "sk-..."},
+)
+```
+
+<Note>
+`acp_env` still works but is deprecated and will be removed in 1.29.0; prefer the secret-registry channels above for environment variables and credentials.
+</Note>
 
 ### Authentication