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, provider model, 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, provider model IDs, 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- A provider model ID such as `gpt-4.1`.
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 `agentclash infra provider-account models <PROVIDER_ACCOUNT_ID>`.
514. List existing deployments with `agentclash deployment list --json` to avoid duplicates.
525. Create the deployment with flags, or with `--from-file` when you need `deployment_config`.
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 <PROVIDER_MODEL_ID>
68```
69
70The CLI requires `--name`, `--agent-build-id`, `--build-version-id`, and `--runtime-profile-id` before it sends a flag-based request. Native deployments also require `provider_account_id` and a nonblank `model`.
71
72Use JSON when you need the complete API shape, including `deployment_config`:
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": "gpt-4.1",
82  "deployment_config": {}
83}
84```
85
86## Commands
87```bash
88export AGENTCLASH_API_URL="https://api.agentclash.dev"
89agentclash doctor
90
91agentclash build get <BUILD_ID>
92agentclash build version get <BUILD_VERSION_ID> --json
93
94agentclash infra runtime-profile get <RUNTIME_PROFILE_ID>
95agentclash infra provider-account get <PROVIDER_ACCOUNT_ID>
96agentclash infra provider-account models <PROVIDER_ACCOUNT_ID>
97
98agentclash deployment list --json
99agentclash deployment create --help
100agentclash deployment create --from-file deployment.json
101agentclash deploy list
102agentclash deploy create --from-file deployment.json
103
104agentclash run create \
105  --challenge-pack-version <CHALLENGE_PACK_VERSION_ID> \
106  --deployments <DEPLOYMENT_ID>
107```
108
109## Expected Output
110- `deployment list --json` returns `items` with deployment `id`, `name`, `status`, `current_build_version_id`, and timestamps.
111- `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`.
112- Human output for deployment creation prints `Created deployment <name> (<id>)`.
113- The deployment ID can be passed to run creation as `agent_deployment_ids` through `agentclash run create --deployments <DEPLOYMENT_ID>`.
114
115## Run Compatibility Checks
116- The deployment should be active in `agentclash deployment list --json`.
117- The deployment should point to the intended ready build version via `current_build_version_id`.
118- Runtime profile settings should satisfy the challenge pack: shell, network, timeout, max iterations, and max tool calls.
119- Provider account and model should match the build's `model_spec` expectations.
120- Run creation requires at least one deployment. Non-interactive runs use `--deployments`; TTY runs can prompt from active deployments.
121- Backend run creation requires deployment IDs to reference active deployments with snapshots in the selected workspace.
122
123## Failure Modes
124- `no workspace specified`: run `agentclash link`, pass `--workspace`, set `AGENTCLASH_WORKSPACE`, or add project config with `agentclash init`.
125- `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`.
126- `only ready versions can be deployed`: return to `agentclash-agent-build-author`, validate the version, and mark it ready.
127- `provider_account_id is required`: create/select a provider account with `agentclash-runtime-resources-setup`.
128- `model is required`: pass the exact provider model ID with `--model` or in the JSON file.
129- `*_id must be a valid UUID`: copy IDs from `build get`, `build version get --json`, `infra ... get`, or `deployment list --json`.
130- Run creation rejects the deployment: confirm it is active, belongs to the selected workspace, and has a snapshot.
131
132## Safety Notes
133- Do not put raw provider API keys or tokens in `deployment_config`; use workspace secrets and provider accounts.
134- Treat deployment creation as production-affecting when `AGENTCLASH_API_URL` points at hosted production.
135- Use `list` and `get` commands before creating resources to avoid duplicate deployments.
136- Do not invent IDs. If a required ID is missing, run the upstream runtime resources or build authoring skill first.
137- Prefer `--json` for machine-readable checks by coding agents.
138
139## Report Back Format
140```text
141Workspace: <workspace-id>
142Deployment: <name> (<deployment_id>)
143Status: <active | paused | archived | unknown>
144Build: <agent_build_id>
145Build version: <build_version_id> (<ready | blocked>)
146Runtime profile: <runtime_profile_id>
147Provider account: <provider_account_id>
148Model: <provider model ID>
149Run compatibility: <ready | blocked>
150Next skill: agentclash-eval-runner
151Notes: <runtime/model/provider/challenge-pack caveats>
152```
153
154## Related Skills
155- `agentclash-cli-setup`
156- `agentclash-runtime-resources-setup`
157- `agentclash-agent-build-author`
158- `agentclash-eval-runner`
159
160## Related Docs
161- `/docs-md/concepts/agents-and-deployments`
162- `/docs-md/guides/configure-runtime-resources`
163- `/docs-md/reference/cli`
164- `/docs-md/reference/config`