opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add agent workspaces best practices guide (#23142)

Browse Source 
Add a new docs page under /docs/ai-coder/agents/ covering best practices
for creating templates that are discoverable and useful to Coder Agents.

Covers template descriptions, dedicated agent templates, network
boundaries, credential scoping, parameter design, pre-installed tooling,
and prebuilt workspaces for reducing provisioning latency.

<!--

If you have used AI to produce some or all of this PR, please ensure you
have read our [AI Contribution
guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING)
before submitting.

-->
This commit is contained in:
Matt Vollmer
2026-03-17 19:28:46 -04:00
committed by GitHub
parent 903cfb183f
commit 665db7bdeb
3 changed files with 279 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ai-coder/agents/platform-controls/index.md
+137
View File
@@ -0,0 +1,137 @@
# Platform Controls
## Design philosophy
Coder Agents is built on a simple premise: platform teams should have full
control over how agents operate, and developers should have zero configuration
burden.
This means:
- **All agent configuration is admin-level.** Providers, models, system prompts,
and tool permissions are set by platform teams from the control plane. These
are not user preferences — they are deployment-wide policies.
- **Developers never need to configure anything.** A developer just describes
the work they want done. They do not need to pick a provider, enter an API
key, or write a system prompt — the platform team has already set all of
that up. The goal is not to restrict developers, but to make configuration
unnecessary for a great experience.
- **Enforcement, not defaults.** Settings configured by administrators are
enforced server-side. Developers cannot override them. This is a deliberate
distinction — a setting that a user can change is a preference, not a policy.
This is an architectural decision, not just a product choice. Because the agent
loop runs in the control plane rather than inside developer workspaces, there is
no local configuration for developers to modify and no agent software for them
to reconfigure. The control plane is the single source of truth for how agents
behave.
## What platform teams control today
### Providers and models
Administrators configure which LLM providers and models are available from the
Coder dashboard. This includes API keys, base URLs (for enterprise proxies or
self-hosted models), and per-model parameters like context limits, thinking
budgets, and reasoning effort.
Developers select from the set of models an administrator has enabled. They
cannot add their own providers, supply their own API keys, or access models that
have not been explicitly configured.
See [Models](../models.md) for setup instructions.
### System prompt
Administrators can set a system prompt that applies to all agent sessions. This
is useful for establishing organizational conventions — coding standards,
commit message formats, preferred libraries, or repository-specific context.
The system prompt configuration is only accessible to administrators in the
dashboard. Developers do not see or interact with it.
### Template routing
Platform teams control which templates are available to agents and how the agent
selects them. When a developer describes a task, the agent reads template
descriptions to determine which template to provision.
By writing clear template descriptions — for example, "Use this template for
Python backend services in the payments repo" — platform teams can guide the
agent toward the correct infrastructure without requiring developers to
understand template selection at all.
See [Template Optimization](./template-optimization.md) for best practices on writing
discoverable descriptions, configuring network boundaries, scoping credentials,
and designing template parameters for agent use.
## Where we are headed
Coder Agents is in its early stages. The controls above — providers, models,
and system prompt — are what is available today. We are actively building
toward a broader set of platform controls based on what we are hearing from
customers deploying agents in regulated and enterprise environments.
The areas we are investing in include:
### Usage controls and analytics
We plan to give platform teams visibility into how agents are being used across
the organization: token consumption per user, cost per PR, merge rates by model,
and average time from prompt to merged pull request.
The goal is to let platform teams make data-driven decisions — like switching
the default model when analytics show one model produces higher merge rates —
rather than relying on anecdotal feedback from individual developers.
### Infrastructure-level enforcement
We believe that security-critical behaviors should not depend on the system
prompt. A system prompt can instruct an agent to "always format branch names like... ," but there is no guarantee the agent will comply every time.
For controls that matter — network boundaries, git push targets, allowed
hostnames — we intend to enforce them at the infrastructure and network layer.
Examples of what this looks like:
- **Network-restricted templates for agent workloads.** Because the AI comes
from the control plane, agent workspaces do not need outbound access to LLM
providers. You can create templates that only permit access to your git
provider and nothing else.
- **Template scoping for agents.** We intend to let administrators restrict
which templates are available in the agentic interface, separate from what
developers see when manually creating workspaces. This lets you apply stricter
policies to agent-created workspaces without affecting the developer
experience for manually-created ones.
### Tool customization
The agent ships with a standard set of tools (file read/write, shell execution,
sub-agents). We intend to let platform teams customize the available tool set —
adding organization-specific tools or restricting default ones — without
modifying agent source code.
## Why we take this approach
The common pattern in the industry today is that each developer installs and
configures their own coding agent inside their development environment. This
creates several problems for platform teams:
- **No standardization.** Different developers use different agents with
different configurations. There is no unified way to enforce conventions or
improve the experience across the organization.
- **Security is ad-hoc.** If the agent runs inside the workspace, it has access
to whatever the workspace has access to — API keys, network endpoints,
credentials. Restricting this requires per-workspace configuration that is
difficult to maintain at scale.
- **Feedback is anecdotal.** Without centralized analytics, platform teams have
no way to know which models perform best, which prompts cause failures, or how
much agents are costing the organization.
- **Configuration is a developer burden.** Developers — especially those who
are not power users — should not need to think about which agent to install,
which API key to use, or how to configure a system prompt. They should
describe the work they want done.
As models improve and the differences between agent harnesses continue to
shrink, we believe the leverage shifts toward user experience and platform-level controls: which
models to offer, how to enforce security, and how to use analytics to
continuously improve the development experience across the organization.
docs/ai-coder/agents/platform-controls/template-optimization.md
+258
View File
@@ -0,0 +1,258 @@
# Template Routing
Not every chat with Coder Agents requires a workspace. A workspace is only provisioned when the
agent decides it needs compute — to read files, write code, run commands, or
execute builds.
When a workspace is needed, the agent reads the available templates, selects
the appropriate one based on its name and description, and provisions a
workspace automatically.
This guide covers best practices for creating templates that are discoverable
and useful to Coder Agents.
## Write discoverable template descriptions
The agent selects templates by reading their names and descriptions — the same
metadata shown on the templates page in the Coder dashboard, sorted by number
of active developers. It does not inspect the template's Terraform to
understand what infrastructure is inside.
This means the template description is the single most important factor in
whether the agent picks the right template for a given task.
### What to include
A good template description tells the agent:
- What language, framework, or stack the template is for.
- Which repository or service it targets, if applicable.
- What type of work it supports (e.g., backend services, frontend apps, data
pipelines).
### Examples
| Description | Why it works |
|---------------------------------------------------------------------------------------------|--------------------------------------------------------------------|
| Python backend services for the payments repo. Includes Poetry, Python 3.12, and PostgreSQL | Specific language, repo, and toolchain |
| React frontend development for the customer portal. Node 20, pnpm, Storybook pre-installed | Clear stack, named project, key tools listed |
| General-purpose Go development environment with Go 1.23, Docker, and common CLI tools | Broad but descriptive — the agent can match it to Go-related tasks |
| Java microservices for the order-processing pipeline. Maven, JDK 21, Kafka client libraries | Names the service domain and build tool |
| Description | Why it fails |
|--------------------|-------------------------------------------------------------------------|
| Team A template v2 | No information about what the template is for |
| Dev environment | Too generic — the agent cannot distinguish this from any other template |
| k8s-prod-2024 | Internal shorthand that carries no meaning for the agent |
| Default | Tells the agent nothing |
> [!TIP]
> If many developers already use a template, the agent is more likely to
> select it because templates are sorted by active developer count. A
> well-written description on a popular template is the strongest routing
> signal you can provide.
### Template display names
Display names appear in the template selector and in the agent's tool output.
Use readable, descriptive names rather than slugs or internal codes. A display
name like "Python Backend (Payments)" is more useful to both humans and the
agent than `py-be-pay-v3`.
## Create dedicated agent templates
Rather than reusing your standard interactive developer templates for agent
workloads, consider creating dedicated templates with configurations
appropriate for unattended, agent-driven work.
Agent templates differ from developer templates in several ways:
- **No IDE tooling needed.** The agent connects via the workspace daemon's HTTP
API, not through VS Code or JetBrains. You can omit IDE-specific
configuration, extensions, and desktop tools.
- **Stricter network policies.** Agent workspaces typically need access to only
the control plane and your git provider. You can apply tighter egress rules
than you would for a developer who needs to browse documentation or access
additional services.
- **Reduced permissions.** Agent workspaces can use scoped credentials with
fewer permissions than a developer's interactive session.
See [Creating templates](../../../admin/templates/creating-templates.md) for
step-by-step instructions on creating templates via the UI, CLI, or CI/CD.
## Configure network boundaries
The workspace is the network boundary for the agent. If you want to control
what the agent can access, control what the workspace can access.
This is a deliberate architectural advantage of running the agent loop in the
control plane. Because all AI functionality — LLM inference, tool dispatch,
chat state — lives in the control plane, agent workspaces do not need outbound
access to any LLM provider. The workspace only needs to reach:
- **The Coder control plane** — required for the workspace daemon to function.
- **Your git provider** — required for push and pull operations.
Everything else can be blocked at the network level.
### Why network boundaries are more effective than process-level controls
Traditional approaches to restricting agent behavior — such as blocking
specific commands at the process level — are difficult to enforce reliably. An
agent executing arbitrary shell commands can find alternative paths to achieve
the same result (aliasing commands, writing scripts, using different tools).
Network-level boundaries are more robust because they operate below the process
layer. If the workspace cannot reach an external service, it does not matter
what command the agent runs — the connection simply fails. This provides a
firmer security guarantee than trying to restrict individual process behaviors.
See [Architecture](../architecture.md#workspaces-can-be-fully-network-isolated)
for more detail on the security model.
## Scope permissions and credentials
The agent operates with the same identity and permissions as the user who
submitted the prompt. There is no privilege escalation — if a developer cannot
access a resource through the Coder dashboard, the agent cannot access it
either.
### External service credentials
When agent workspaces need access to external services (git providers, package
registries, artifact stores), configure credentials with the minimum scope
required:
- **Use separate tokens for agent templates.** Rather than sharing the same
broad-scope token used by developer workspaces, create a dedicated token with
only the permissions the agent needs (e.g., read/write access to specific
repositories, no admin access).
- **Configure external auth at the template level.** Use Coder's
[external authentication](../../../admin/external-auth/index.md) to provide scoped
git credentials. The agent uses the same external auth flow as any other
workspace, so credentials are managed centrally.
- **Avoid injecting long-lived secrets.** Prefer short-lived tokens or
credential helpers over static API keys baked into the template image.
### Git identity
Every git operation the agent performs — commits, pushes, pull requests — is
attributed to the user who submitted the prompt. This happens through the
existing git authentication configured in your Coder deployment. There is no
shared bot account.
Ensure your templates configure git with the appropriate author information so
that commits are properly attributed. The agent does not override git
configuration — it uses whatever is set in the workspace environment.
## Design template parameters for automation
The agent can read template parameters — including their names, descriptions,
and defaults — and fill them in when creating a workspace. Well-designed
parameters help the agent provision the right infrastructure without human
intervention.
### Keep parameters simple
- **Use sensible defaults.** The agent performs best when most parameters have
reasonable defaults and only a few require explicit selection. A template
with ten required parameters and no defaults forces the agent to guess.
- **Minimize required parameters.** If a parameter is not essential for the
agent's use case, give it a default value or make it optional.
### Write descriptive parameter metadata
The agent reads `display_name` and `description` fields to understand what a
parameter controls. Treat these the same way you treat template descriptions —
be specific and use natural language.
```hcl
data "coder_parameter" "region" {
name = "region"
display_name = "Deployment Region"
type = "string"
description = "AWS region for the workspace. Use us-east-1 for the payments service or eu-west-1 for GDPR-regulated workloads."
default = "us-east-1"
}
```
A description like "AWS region" is less useful to the agent than one that
explains when to use each option.
### Avoid opaque identifiers
Parameters with values like `ami-0abcdef1234567890` or `subnet-12345` are
difficult for the agent to reason about. Where possible, use human-readable
option labels or map opaque IDs to descriptive names using Terraform locals.
For full parameter reference — including types, validation, mutability, and
workspace presets — see
[Parameters](../../../admin/templates/extending-templates/parameters.md).
[Dynamic parameters](../../../admin/templates/extending-templates/dynamic-parameters.md)
add conditional form controls and identity-aware defaults for more advanced
use cases.
## Pre-install tools and dependencies
Agent workspaces should be ready to work immediately after provisioning. The
agent does not know how to install your organization's specific toolchain, and
time spent installing dependencies is time not spent on the task.
### What to pre-install
- **Language runtimes and build tools** for the target stack (e.g., Go, Node,
Python, Maven).
- **Common CLI tools** the agent is likely to use: `git`, `curl`, `jq`, `make`,
`docker` (if applicable).
- **Project-specific dependencies.** If the template targets a specific
repository, consider pre-installing the project's dependencies or running the
setup script as part of workspace startup.
- **Git configuration.** Ensure `git` is configured with credentials and author
information so the agent can commit and push without additional setup.
For guidance on building and maintaining workspace images, see
[Image management](../../../admin/templates/managing-templates/image-management.md).
### Set a meaningful working directory
If the template targets a specific repository, pre-clone it and set the
working directory so the agent starts in the right place:
```hcl
resource "coder_agent" "main" {
os = "linux"
arch = "amd64"
dir = "/home/coder/payments-service"
}
```
This avoids a round trip where the agent needs to figure out where the code
lives before it can begin working.
## Use prebuilt workspaces to reduce provisioning time
Workspace provisioning is the primary source of latency when the agent begins a
task. Templates with complex infrastructure, large images, or lengthy startup
scripts can take minutes to provision — time where the developer is waiting
and the agent is idle.
[Prebuilt workspaces](../../../admin/templates/extending-templates/prebuilt-workspaces.md)
eliminate this delay by maintaining a pool of ready-to-use workspaces for
specific parameter presets. When the agent creates a workspace that matches a
preset, Coder assigns an already-running prebuilt workspace instead of
provisioning from scratch. The agent can begin working immediately.
## Checklist
Use this as a quick reference when creating or updating templates for Coder
Agents:
- [ ] Template has a specific, natural-language description that includes
language, framework, and target project or service.
- [ ] Display name is readable and descriptive.
- [ ] Network egress is restricted to the control plane and git provider.
- [ ] External service credentials use minimal-scope tokens.
- [ ] Template parameters have sensible defaults and descriptive metadata.
- [ ] Language runtimes, build tools, and git are pre-installed.
- [ ] Prebuilt workspaces are configured for high-traffic presets (Premium).
- [ ] Working directory is set to the target repository (if applicable).