agentclash-agent-deployment-setup

Files (1)

• SKILL.md

SKILL.md (first lines)

# AgentClash Agent Deployment Setup

## Purpose
Turn a ready AgentClash build version plus runtime/provider/model resources into an active deployment ID that runs and eval sessions can select.

## Use When
- A user has a ready build version and runtime resources, but no deployment ID yet.
- A run or eval flow needs `agent_deployment_ids`.
- A deployment create request is failing because build version readiness, provider account, provider model, runtime profile, or workspace context is wrong.
- A coding agent needs to audit whether an existing deployment is runnable before starting `agentclash run create` or `agentclash eval start`.

## Do Not Use When
- The CLI is not authenticated or no workspace is selected; use `agentclash-cli-setup` first.
- Provider accounts, provider model IDs, runtime profiles, workspace secrets, or workspace tools are missing; use `agentclash-runtime-resources-setup` first.
- The build version is still a draft or has validation errors; use `agentclash-agent-build-author` first.
- The user is authoring challenge pack YAML or choosing input sets; use challenge-pack skills.

## Inputs Needed
- Workspace ID and confirmation that `agentclash doctor` can reach it.
- Deployment name.
- `agent_build_id` and ready `build_version_id`.
- `runtime_profile_id`.
- `provider_account_id`.
- A provider model ID such as `gpt-4.1`.
- Optional `deployment_config` JSON object.
- Challenge pack or run requirements that affect runtime profile, tool, network, shell, or model compatibility.

## Environment
Use hosted production by default:

```bash
export AGENTCLASH_API_URL="https://api.agentclash.dev"
agentclash doctor
```

Commands that list or create deployments need a resolved workspace. Use `agentclash workspace use <workspace-id>`, `--workspace`, `AGENTCLASH_WORKSPACE`, or project config from `agentclash init`.

## Procedure
1. Verify CLI auth and workspace context with `agentclash doctor`.
2. 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`.
3. 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>`.
4. List existing deployments with `agentclash deployment list --json` to avoid duplicates.
5. Create the deployment with flags, or with `--from-file` when you need `deployment_config`.
6. Re-list deployments and record the created deployment ID, status, and `current_build_version_id`.
7. Check run compatibility by confirming the deployment is active and can be passed to `agentclash run create --deployments <DEPLOYMENT_ID>`.
8. Report deployment IDs and any blockers for `agentclash-eval-runner`.

## Deployment Contract
Flag-based creation requires these CLI flags when `--from-file` is not used:

```bash
agentclash deployment create \
  --name support-bot-prod \
  --agent-build-id <AGENT_BUILD_ID> \
  --build-version-id <BUILD_VERSION_ID> \
  --runtime-profile-id <RUNTIME_PROFILE_ID> \
  --provider-account-id <PROVIDER_ACCOUNT_ID> \
  --model <PROVIDER_MODEL_ID>
```

The 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`.

Use JSON when you need the complete API shape, including `deployment_config`:

```json
{
  "name": "support-bot-prod",
  "agent_build_id": "<AGENT_BUILD_ID>",
  "build_version_id": "<BUILD_VERSION_ID>",
  "runtime_profile_id": "<RUNTIME_PROFILE_ID>",
  "provider_account_id": "<PROVIDER_ACCOUNT_ID>",
  "model": "gpt-4.1",
  "deployment_config": {}
}
```

## Commands
```bash
export AGENTCLASH_API_URL="https://api.agentclash.dev"
agentclash doctor

agentclash build get <BUILD_ID>
agentclash build version get <BUILD_VERSION_ID> --json

agentclash infra runtime-profile get <RUNTIME_PROFILE_ID>
agentclash infra provider-account get <PROVIDER_ACCOUNT_ID>
agentclash infra provider-account models <PROVIDER_ACCOUNT_ID>

agentclash deployment list --json
agentclash deployment create --help
agentclash deployment create --from-file deployment.json
agentclash deploy list
agentclash deploy create --from-file deployment.json

agentclash run create \
  --challenge-pack-version <CHALLENGE_PACK_VERSION_ID> \
  --deployments <DEPLOYMENT_ID>
```

## Expected Output
- `deployment list --json` returns `items` with deployment `id`, `name`, `status`, `current_build_version_id`, and timestamps.
- `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`.
- Human output for deployment creation prints `Created deployment <name> (<id>)`.
- The deployment ID can be passed to run creation as `agent_deployment_ids` through `agentclash run create --deployments <DEPLOYMENT_ID>`.

## Run Compatibility Checks
- The deployment should be active in `agentclash deployment list --json`.
- The deployment should point to the intended ready build version via `current_build_version_id`.
- Runtime profile settings should satisfy the challenge pack: shell, network, timeout, max iterations, and max tool calls.
- Provider account and model should match the build's `model_spec` expectations.
- Run creation requires at least one deployment. Non-interactive runs use `--deployments`; TTY runs can prompt from active deployments.
- Backend run creation requires deployment IDs to reference active deployments with snapshots in the selected workspace.

## Failure Modes
- `no workspace specified`: run `agentclash link`, pass `--workspace`, set `AGENTCLASH_WORKSPACE`, or add project config with `agentclash init`.
- `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`.
- `only ready versions can be deployed`: return to `agentclash-agent-build-author`, validate the version, and mark it ready.
- `provider_account_id is required`: create/select a provider account with `agentclash-runtime-resources-setup`.
- `model is required`: pass the exact provider model ID with `--model` or in the JSON file.

From agentclash/agentclash, MIT.

More from agentclash/agentclash