Setting the file. One moment.
Skill 79 · Amazon Workspaces Agent Access
Subchapter 79.2
references/connection-modes.mdMarkdown2 KBView on GitHub
Connect mode is an HTTP header, not a tool parameter. There is no
connect_to_desktoptool and no argument. You select the mode with the request header ( or ), sent alongside your streaming-URL/SAML auth.
connection_modeX-Amzn-AgentAccess-Connect-ModeBLOCKINGPOLLINGControl how the agent waits for the desktop session with the X-Amzn-AgentAccess-Connect-Mode header. Applies to both non-domain-joined and domain-joined fleets — set it alongside whichever auth mechanism the fleet uses.
| Mode | Behavior | When to use |
|---|---|---|
BLOCKING (default) | Server waits until the desktop connection is fully established before responding. When tools/list returns, all desktop tools are immediately available. | Simple agents that can afford to wait on connect. |
POLLING | Server responds immediately. tools/list initially returns only the connection_status tool. The agent polls it until the desktop is ready, then the full tool set appears. | The agent wants to do other work while the desktop starts, or you want explicit control over connection-timeout behavior. |
headers = {
"X-Amzn-AgentAccess-Streaming-Session-Url": streaming_url, # non-domain-joined
"X-Amzn-AgentAccess-Connect-Mode": "POLLING",
}
# After initialize, tools/list returns immediately with only connection_status:
tools = await session.list_tools() # -> [connection_status]
# Poll until CONNECTED:
while True:
result = await session.call_tool("connection_status", {})
status = json.loads(result.content[0].text)
if status["state"] == "CONNECTED":
break
await asyncio.sleep(2)
# Now the full desktop tool set is available:
tools = await session.list_tools() # -> screenshot, left_click, type_text, ...Key points:
connection_status reports CONNECTED will not work — only connection_status is exposed until the desktop connects.CONNECTED to pick up the full set.