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:

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:

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:

{
  "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

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.
• *_id must be a valid UUID: copy IDs from build get, build version get --json, infra ... get, or deployment list --json.
• Run creation rejects the deployment: confirm it is active, belongs to the selected workspace, and has a snapshot.

Safety Notes

• Do not put raw provider API keys or tokens in deployment_config; use workspace secrets and provider accounts.
• Treat deployment creation as production-affecting when AGENTCLASH_API_URL points at hosted production.
• Use list and get commands before creating resources to avoid duplicate deployments.
• Do not invent IDs. If a required ID is missing, run the upstream runtime resources or build authoring skill first.
• Prefer --json for machine-readable checks by coding agents.

Report Back Format

Workspace: <workspace-id>
Deployment: <name> (<deployment_id>)
Status: <active | paused | archived | unknown>
Build: <agent_build_id>
Build version: <build_version_id> (<ready | blocked>)
Runtime profile: <runtime_profile_id>
Provider account: <provider_account_id>
Model: <provider model ID>
Run compatibility: <ready | blocked>
Next skill: agentclash-eval-runner
Notes: <runtime/model/provider/challenge-pack caveats>

Related Skills

• agentclash-cli-setup
• agentclash-runtime-resources-setup
• agentclash-agent-build-author
• agentclash-eval-runner

Related Docs

• /docs-md/concepts/agents-and-deployments
• /docs-md/guides/configure-runtime-resources
• /docs-md/reference/cli
• /docs-md/reference/config