Agent Deployment Setup Skill

1---
2name: agentclash-agent-deployment-setup
3description: Use when creating, selecting, or diagnosing AgentClash agent deployments for runs, including ready build versions, runtime profiles, provider/model wiring, deployment IDs, workspace context, and run compatibility.
4metadata:
5  agentclash.role: agent-deployments
6  agentclash.version: "1"
7  agentclash.requires_cli: "true"
8---
9
10# AgentClash Agent Deployment Setup
11
12## Purpose
13Turn a ready AgentClash build version plus runtime/provider/model resources into an active deployment ID that runs and eval sessions can select.
14
15## Use When
16- A user has a ready build version and runtime resources, but no deployment ID yet.
17- A run or eval flow needs `agent_deployment_ids`.
18- A deployment create request is failing because build version readiness, provider account, model alias, runtime profile, or workspace context is wrong.
19- A coding agent needs to audit whether an existing deployment is runnable before starting `agentclash run create` or `agentclash eval start`.
20
21## Do Not Use When
22- The CLI is not authenticated or no workspace is selected; use `agentclash-cli-setup` first.
23- Provider accounts, model aliases, runtime profiles, workspace secrets, or workspace tools are missing; use `agentclash-runtime-resources-setup` first.
24- The build version is still a draft or has validation errors; use `agentclash-agent-build-author` first.
25- The user is authoring challenge pack YAML or choosing input sets; use challenge-pack skills.
26
27## Inputs Needed
28- Workspace ID and confirmation that `agentclash doctor` can reach it.
29- Deployment name.
30- `agent_build_id` and ready `build_version_id`.
31- `runtime_profile_id`.
32- `provider_account_id`.
33- `model_alias_id`, or a raw provider model string such as `gpt-4.1` when creating from JSON so the backend can auto-create/reuse a model alias.
34- Optional `deployment_config` JSON object.
35- Challenge pack or run requirements that affect runtime profile, tool, network, shell, or model compatibility.
36
37## Environment
38Use hosted production by default:
39
40```bash
41export AGENTCLASH_API_URL="https://api.agentclash.dev"
42agentclash doctor
43```
44
45Commands that list or create deployments need a resolved workspace. Use `agentclash workspace use <workspace-id>`, `--workspace`, `AGENTCLASH_WORKSPACE`, or project config from `agentclash init`.
46
47## Procedure
481. Verify CLI auth and workspace context with `agentclash doctor`.
492. Inspect the build and build version with `agentclash build get <BUILD_ID>` and `agentclash build version get <BUILD_VERSION_ID> --json`. Stop if `version_status` is not `ready`.
503. Confirm runtime resources exist: `agentclash infra runtime-profile get <RUNTIME_PROFILE_ID>`, `agentclash infra provider-account get <PROVIDER_ACCOUNT_ID>`, and either `agentclash infra model-alias get <MODEL_ALIAS_ID>` or a raw model value for JSON-file creation.
514. List existing deployments with `agentclash deployment list --json` to avoid duplicates.
525. Create the deployment with flags when you already have a model alias ID, or with `--from-file` when you need `deployment_config` or raw `model` auto-alias behavior.
536. Re-list deployments and record the created deployment ID, status, and `current_build_version_id`.
547. Check run compatibility by confirming the deployment is active and can be passed to `agentclash run create --deployments <DEPLOYMENT_ID>`.
558. Report deployment IDs and any blockers for `agentclash-eval-runner`.
56
57## Deployment Contract
58Flag-based creation requires these CLI flags when `--from-file` is not used:
59
60```bash
61agentclash deployment create \
62  --name support-bot-prod \
63  --agent-build-id <AGENT_BUILD_ID> \
64  --build-version-id <BUILD_VERSION_ID> \
65  --runtime-profile-id <RUNTIME_PROFILE_ID> \
66  --provider-account-id <PROVIDER_ACCOUNT_ID> \
67  --model-alias-id <MODEL_ALIAS_ID>
68```
69
70The CLI requires `--name`, `--agent-build-id`, `--build-version-id`, and `--runtime-profile-id` before it sends a flag-based request. The backend then requires `provider_account_id` and either `model_alias_id` or `model`.
71
72Use JSON when you need the complete API shape, including `deployment_config` or raw model auto-aliasing:
73
74```json
75{
76  "name": "support-bot-prod",
77  "agent_build_id": "<AGENT_BUILD_ID>",
78  "build_version_id": "<BUILD_VERSION_ID>",
79  "runtime_profile_id": "<RUNTIME_PROFILE_ID>",
80  "provider_account_id": "<PROVIDER_ACCOUNT_ID>",
81  "model_alias_id": "<MODEL_ALIAS_ID>",
82  "deployment_config": {}
83}
84```
85
86Raw model auto-alias path:
87
88```json
89{
90  "name": "support-bot-prod",
91  "agent_build_id": "<AGENT_BUILD_ID>",
92  "build_version_id": "<BUILD_VERSION_ID>",
93  "runtime_profile_id": "<RUNTIME_PROFILE_ID>",
94  "provider_account_id": "<PROVIDER_ACCOUNT_ID>",
95  "model": "gpt-4.1",
96  "deployment_config": {}
97}
98```
99
100When `provider_account_id` plus `model` is supplied and `model_alias_id` is omitted, the backend looks up the provider account, upserts a model catalog entry, and reuses/unarchives/creates a model alias.
101
102## Commands
103```bash
104export AGENTCLASH_API_URL="https://api.agentclash.dev"
105agentclash doctor
106
107agentclash build get <BUILD_ID>
108agentclash build version get <BUILD_VERSION_ID> --json
109
110agentclash infra runtime-profile get <RUNTIME_PROFILE_ID>
111agentclash infra provider-account get <PROVIDER_ACCOUNT_ID>
112agentclash infra model-alias get <MODEL_ALIAS_ID>
113
114agentclash deployment list --json
115agentclash deployment create --help
116agentclash deployment create --from-file deployment.json
117agentclash deploy list
118agentclash deploy create --from-file deployment.json
119
120agentclash run create \
121  --challenge-pack-version <CHALLENGE_PACK_VERSION_ID> \
122  --deployments <DEPLOYMENT_ID>
123```
124
125## Expected Output
126- `deployment list --json` returns `items` with deployment `id`, `name`, `status`, `current_build_version_id`, and timestamps.
127- `deployment create` returns a created deployment with `id`, `workspace_id`, `agent_build_id`, `current_build_version_id`, `name`, `slug`, `deployment_type`, `status`, `created_at`, and `updated_at`.
128- Human output for deployment creation prints `Created deployment <name> (<id>)`.
129- The deployment ID can be passed to run creation as `agent_deployment_ids` through `agentclash run create --deployments <DEPLOYMENT_ID>`.
130
131## Run Compatibility Checks
132- The deployment should be active in `agentclash deployment list --json`.
133- The deployment should point to the intended ready build version via `current_build_version_id`.
134- Runtime profile settings should satisfy the challenge pack: shell, network, timeout, max iterations, and max tool calls.
135- Provider account and model alias should match the build's `model_spec` expectations.
136- Run creation requires at least one deployment. Non-interactive runs use `--deployments`; TTY runs can prompt from active deployments.
137- Backend run creation requires deployment IDs to reference active deployments with snapshots in the selected workspace.
138
139## Failure Modes
140- `no workspace specified`: run `agentclash link`, pass `--workspace`, set `AGENTCLASH_WORKSPACE`, or add project config with `agentclash init`.
141- `missing required flags when --from-file is not used`: pass `--name`, `--agent-build-id`, `--build-version-id`, and `--runtime-profile-id`, or use `--from-file`.
142- `only ready versions can be deployed`: return to `agentclash-agent-build-author`, validate the version, and mark it ready.
143- `provider_account_id is required`: create/select a provider account with `agentclash-runtime-resources-setup`.
144- `either model_alias_id or model ... is required`: pass `--model-alias-id` with flags, or use `--from-file` with either `model_alias_id` or raw `model`.
145- `*_id must be a valid UUID`: copy IDs from `build get`, `build version get --json`, `infra ... get`, or `deployment list --json`.
146- Run creation rejects the deployment: confirm it is active, belongs to the selected workspace, and has a snapshot.
147
148## Safety Notes
149- Do not put raw provider API keys or tokens in `deployment_config`; use workspace secrets and provider accounts.
150- Treat deployment creation as production-affecting when `AGENTCLASH_API_URL` points at hosted production.
151- Use `list` and `get` commands before creating resources to avoid duplicate deployments.
152- Do not invent IDs. If a required ID is missing, run the upstream runtime resources or build authoring skill first.
153- Prefer `--json` for machine-readable checks by coding agents.
154
155## Report Back Format
156```text
157Workspace: <workspace-id>
158Deployment: <name> (<deployment_id>)
159Status: <active | paused | archived | unknown>
160Build: <agent_build_id>
161Build version: <build_version_id> (<ready | blocked>)
162Runtime profile: <runtime_profile_id>
163Provider account: <provider_account_id>
164Model: <model_alias_id | raw model auto-alias>
165Run compatibility: <ready | blocked>
166Next skill: agentclash-eval-runner
167Notes: <runtime/model/provider/challenge-pack caveats>
168```
169
170## Related Skills
171- `agentclash-cli-setup`
172- `agentclash-runtime-resources-setup`
173- `agentclash-agent-build-author`
174- `agentclash-eval-runner`
175
176## Related Docs
177- `/docs-md/concepts/agents-and-deployments`
178- `/docs-md/guides/configure-runtime-resources`
179- `/docs-md/reference/cli`
180- `/docs-md/reference/config`