manage-agent

Name: manage-agent
Author: microsoft

372stars76forks

How to install manage-agent?

microsoft/skills-for-copilot-studio/manage-agent

$npx -y skills add microsoft/skills-for-copilot-studio --skill manage-agent

Installs into the current project.

Summary

Push/pull Copilot Studio agent content via the VS Code extension's LanguageServerHost LSP binary. Handles authentication (interactive browser login for push/pull, device code flow for chat token), sync push, sync pull, clone, and diff operations.

Files · 1

View on GitHub

SKILL.md

1	# Manage Agent
2
3	Push and pull Copilot Studio agent content by calling the VS Code extension's LanguageServerHost binary directly, using the same custom LSP protocol the extension uses internally.
4
5	## IMPORTANT: Do Not Modify Scripts
6
7	This is a new capability under active development. The manage-agent scripts (`manage-agent.bundle.js`, `chat-with-agent.bundle.js`) are pre-built bundles that must not be modified, patched, or monkey-patched. If a script fails:
8
9	1. Report the error as-is — show the user the full error output
10	2. Do not attempt to fix, patch, or work around script errors — the scripts interact with the LSP binary using a specific protocol and any modifications will break things
11	3. Direct the user to raise an issue at https://github.com/microsoft/skills-for-copilot-studio/issues with the error output
12	4. Suggest using the VS Code extension directly — the user can perform the same push/pull/clone operations from the Copilot Studio VS Code extension UI as a fallback
13
14	## Prerequisites
15
16	1. Copilot Studio VS Code extension must be installed (`ms-copilotstudio.vscode-copilotstudio`).
17	2. Azure AD app registration (optional) — only needed for device code flow (`auth` command). If `--client-id` is omitted, the script uses VS Code's first-party client ID with interactive browser login instead.
18	3. Environment details — tenant ID, environment ID, environment URL, and agent management URL. These come from the `.mcs/conn.json` inside a cloned agent workspace (created automatically during clone).
19
20	## Phase 0: Resolve Configuration
21
22	Search for `.mcs/conn.json` in the workspace and nearby directories to find existing connection details. The script auto-reads environment details from `conn.json`. If no `conn.json` is found, ask the user for the required parameters.
23
24	## Phase 1: Authenticate
25
26	There are two different auth flows depending on the operation:
27
28	### For push / pull / clone / changes / list-agents (interactive browser login)
29
30	These commands use VS Code's first-party client ID with the Island API gateway. Authentication is interactive — a browser window opens automatically for sign-in. No manual code entry is needed.
31
32	- On first use, a browser window opens for Microsoft sign-in
33	- Tokens are cached in the OS credential store and silently refreshed for ~90 days
34	- After ~90 days, the browser will open again for re-authentication
35
36	No separate auth step is needed before push/pull. The commands handle token acquisition automatically. Just run the command directly (Phase 2).
37
38	### For the `auth` command (device code flow — chat/test token)
39
40	The `auth` command acquires a generic `api.powerplatform.com` token using device code flow. This token is used by the chat and test skills, not by push/pull.
41
42	Run with a 5-minute timeout:
43
44	```bash
45	node ${CLAUDE_SKILL_DIR}/../../scripts/manage-agent.bundle.js auth \
46	--tenant-id "<tenantId>" \
47	--client-id "<clientId>" \
48	--environment-url "<environmentUrl>"
49	```
50
51	Timeout: 300000ms (5 minutes) — set this on the Bash tool call.
52
53	### Token caching and silent refresh
54
55	Tokens and MSAL refresh tokens are persisted in the OS credential store (macOS Keychain, Windows DPAPI, Linux secret-tool). After initial authentication:
56	- Access tokens are valid for ~1 hour
57	- Refresh tokens are valid for ~90 days
58	- The script automatically refreshes expired access tokens silently using the cached refresh token
59	- Re-authentication is only needed on the very first use or after ~90 days
60
61	### When device code flow starts (auth command only)
62
63	The script emits a JSON line to stdout:
64
65	```json
66	{"status":"device_code","userCode":"XXXXXXXX","verificationUri":"https://login.microsoft.com/device","message":"...","expiresIn":900}
67	```
68
69	When you see this in the output, immediately tell the user:
70
71	> Authentication Required
72	>
73	> Please open {verificationUri} in your browser and enter code {userCode}
74	>
75	> The command is waiting for you to complete sign-in. You have {expiresIn/60} minutes.
76
77	The command will automatically continue once the user completes authentication. Do NOT cancel the command — it is waiting for the browser sign-in to complete.
78
79	Two tokens are acquired sequentially (Copilot Studio API, then Dataverse API), so the user may need to authenticate twice on first use.
80
81	### If the command completes with `status: "ok"`
82
83	Tokens are cached. Proceed to Phase 2.
84
85	### If the command fails with `device_code_expired`
86
87	The user didn't authenticate in time.

People who liked this also viewed

6 picks

Type

manage-agent

372stars76forks

View on GitHub

How to install manage-agent?

microsoft/skills-for-copilot-studio/manage-agent

$npx -y skills add microsoft/skills-for-copilot-studio --skill manage-agent

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Manage Agent
2
3	Push and pull Copilot Studio agent content by calling the VS Code extension's LanguageServerHost binary directly, using the same custom LSP protocol the extension uses internally.
4
5	## IMPORTANT: Do Not Modify Scripts
6
7	This is a new capability under active development. The manage-agent scripts (`manage-agent.bundle.js`, `chat-with-agent.bundle.js`) are pre-built bundles that must not be modified, patched, or monkey-patched. If a script fails:
8
9	1. Report the error as-is — show the user the full error output
10	2. Do not attempt to fix, patch, or work around script errors — the scripts interact with the LSP binary using a specific protocol and any modifications will break things
11	3. Direct the user to raise an issue at https://github.com/microsoft/skills-for-copilot-studio/issues with the error output
12	4. Suggest using the VS Code extension directly — the user can perform the same push/pull/clone operations from the Copilot Studio VS Code extension UI as a fallback
13
14	## Prerequisites
15
16	1. Copilot Studio VS Code extension must be installed (`ms-copilotstudio.vscode-copilotstudio`).
17	2. Azure AD app registration (optional) — only needed for device code flow (`auth` command). If `--client-id` is omitted, the script uses VS Code's first-party client ID with interactive browser login instead.
18	3. Environment details — tenant ID, environment ID, environment URL, and agent management URL. These come from the `.mcs/conn.json` inside a cloned agent workspace (created automatically during clone).
19
20	## Phase 0: Resolve Configuration
21
22	Search for `.mcs/conn.json` in the workspace and nearby directories to find existing connection details. The script auto-reads environment details from `conn.json`. If no `conn.json` is found, ask the user for the required parameters.
23
24	## Phase 1: Authenticate
25
26	There are two different auth flows depending on the operation:
27
28	### For push / pull / clone / changes / list-agents (interactive browser login)
29
30	These commands use VS Code's first-party client ID with the Island API gateway. Authentication is interactive — a browser window opens automatically for sign-in. No manual code entry is needed.
31
32	- On first use, a browser window opens for Microsoft sign-in
33	- Tokens are cached in the OS credential store and silently refreshed for ~90 days
34	- After ~90 days, the browser will open again for re-authentication
35
36	No separate auth step is needed before push/pull. The commands handle token acquisition automatically. Just run the command directly (Phase 2).
37
38	### For the `auth` command (device code flow — chat/test token)
39
40	The `auth` command acquires a generic `api.powerplatform.com` token using device code flow. This token is used by the chat and test skills, not by push/pull.
41
42	Run with a 5-minute timeout:
43
44	```bash
45	node ${CLAUDE_SKILL_DIR}/../../scripts/manage-agent.bundle.js auth \
46	--tenant-id "<tenantId>" \
47	--client-id "<clientId>" \
48	--environment-url "<environmentUrl>"
49	```
50
51	Timeout: 300000ms (5 minutes) — set this on the Bash tool call.
52
53	### Token caching and silent refresh
54
55	Tokens and MSAL refresh tokens are persisted in the OS credential store (macOS Keychain, Windows DPAPI, Linux secret-tool). After initial authentication:
56	- Access tokens are valid for ~1 hour
57	- Refresh tokens are valid for ~90 days
58	- The script automatically refreshes expired access tokens silently using the cached refresh token
59	- Re-authentication is only needed on the very first use or after ~90 days
60
61	### When device code flow starts (auth command only)
62
63	The script emits a JSON line to stdout:
64
65	```json
66	{"status":"device_code","userCode":"XXXXXXXX","verificationUri":"https://login.microsoft.com/device","message":"...","expiresIn":900}
67	```
68
69	When you see this in the output, immediately tell the user:
70
71	> Authentication Required
72	>
73	> Please open {verificationUri} in your browser and enter code {userCode}
74	>
75	> The command is waiting for you to complete sign-in. You have {expiresIn/60} minutes.
76
77	The command will automatically continue once the user completes authentication. Do NOT cancel the command — it is waiting for the browser sign-in to complete.
78
79	Two tokens are acquired sequentially (Copilot Studio API, then Dataverse API), so the user may need to authenticate twice on first use.
80
81	### If the command completes with `status: "ok"`
82
83	Tokens are cached. Proceed to Phase 2.
84
85	### If the command fails with `device_code_expired`
86
87	The user didn't authenticate in time.

People who liked this also viewed

6 picks

Type