# Agents and Deployments

Understand how AgentClash turns a build plus runtime/provider resources into a concrete deployment that can be scheduled into a run.

Source: https://www.agentclash.dev/docs/concepts/agents-and-deployments
Markdown export: https://www.agentclash.dev/md/docs/concepts/agents-and-deployments

A deployment is the workspace-scoped runnable target that AgentClash can attach to a run.

## Why a deployment exists at all

AgentClash is stricter than a typical playground because it has to compare like with like. A model name by itself is not enough. The scheduler needs a concrete object that says:

- which build is being run
- which build version is current
- which runtime policy applies
- which provider credentials and provider model are attached

That concrete object is the deployment.

## The current creation contract

The current API schema for `CreateAgentDeploymentRequest` requires:

- `name`
- `agent_build_id`
- `build_version_id`
- `runtime_profile_id`

It also supports these optional fields:

- `provider_account_id`
- `model`
- `deployment_config`

The OpenAPI description also says only ready build versions can be deployed. A build version is "ready" once its status has moved from `draft` to `ready` (the other terminal status is `archived`); a draft or archived version cannot be attached to a deployment.

<DiagramAgentsToRun />

## Runtime profiles are the execution envelope

A runtime profile defines how aggressive or constrained execution should be. In the current API and web types, a runtime profile carries fields like:

- `execution_target`
- `trace_mode`
- `max_iterations`
- `max_tool_calls`
- `step_timeout_seconds`
- `run_timeout_seconds`
- `profile_config`

That last field matters. The native executor reads runtime-profile sandbox overrides from `profile_config`, including things like filesystem roots and `allow_shell` or `allow_network` toggles.

The clean mental model is:

- the challenge pack defines what the workload wants
- the runtime profile defines execution ceilings and local overrides
- the deployment binds those choices to a runnable target

## Provider accounts are how credentials enter the system

A provider account is a workspace resource with:

- `provider_key`
- `name`
- `credential_reference`
- optional `limits_config`

The important detail is how credentials are stored.

If you create a provider account with a raw `api_key`, the infrastructure manager stores that value as a workspace secret and rewrites the credential reference automatically to:

```text
workspace-secret://PROVIDER_<PROVIDER_KEY>_API_KEY
```

So the product already prefers indirection over plaintext credentials on the resource itself.

## Provider model IDs are explicit

Deployments now store the provider's model identifier directly. Use `agentclash infra provider-account models <PROVIDER_ACCOUNT_ID>` to discover models reachable with an account, then pass the selected ID as `model`. Deployment snapshots preserve that value for historical runs.

## A deployment is where these pieces come together

A good way to think about the chain is:

- agent build version: what logic is being deployed
- runtime profile: how it is allowed to execute
- provider account: which credentials or spend limits back external model calls
- model: which provider model the deployment should use consistently
- deployment: the runnable handle used by runs

This is why the docs should not collapse deployment into “selected model.” The object is richer than that.

## What the UI and CLI expose today

The current repo already exposes the resource model across multiple surfaces:

- CLI `deployment create` and `deployment list`
- workspace pages for runtime profiles, provider accounts, deployments, secrets, and tools
- run creation UI that asks for challenge pack and deployment selection separately

That separation is deliberate. A run is an execution event. A deployment is reusable infrastructure state.

## What is stable versus still moving

The dependency chain and the API surface are stable: the fields documented above are the contract you build against today.

What is still moving is the editing experience and automation around these resources:

- how richly each resource can be edited in the UI
- how much automation exists for creating and wiring them together

Treat the resource model itself as real and rely on it, but expect the UX around editing deployments to keep improving.

## See also

- [Configure Runtime Resources](../guides/configure-runtime-resources)
- [Challenge Packs and Inputs](../concepts/challenge-packs-and-inputs)
- [Tools, Network, and Secrets](../concepts/tools-network-and-secrets)
- [CLI Reference](../reference/cli)
- [Datasets overview](https://www.agentclash.dev/md/docs/guides/datasets-overview)
- [Multi-turn packs](https://www.agentclash.dev/md/docs/challenge-packs/multi-turn)
- [Security evaluation](https://www.agentclash.dev/md/docs/guides/security-evaluation)