Module 05 · What the platform offers · 30 min · You are: Platform team
Agents: the platform's second kind of user
In this module
- You learn: Why a coding agent is a user of the platform and not a feature of an IDE, what it needs that people do not (its own identity, an interface it can call, written instructions, limits), and the three causes of excessive agency: too much functionality, too many permissions, too much autonomy.
- You do: Add the coding agent as a user with its own problems. Open the capabilities agents need to them, through an API or MCP. Put an AGENTS.md into the golden path. Write the agent policy: default deny, an identity per agent, what each may do in dev and prod, a human approval for anything that changes prod, a monthly budget and an audit log. Then hand an agent a person's token, as teams do when they are in a hurry, and see the check refuse it.
- You end with:
platform.yamlhas a third user,coding-agent, of kindagent. Nine capabilities listagentsas users. The path isfor: [humans, agents]and namesgolden-paths/new-service/AGENTS.md.agents/policy.yamlpasses the check with two agents.
Coding agents already open pull requests, run tests and read logs, and they do it through whatever access the developer next to them has. That makes them users of the platform, whether the platform knows it or not. The safe version is the same one people get: a golden path, an interface, written context, and access limited to what the job needs. OWASP LLM06:2025 Excessive Agency calls the failure "excessive agency" and names three causes: "excessive functionality", "excessive permissions" and "excessive autonomy". Each one is a field in the policy you write here.
Open this module in the interactive course to track progress.
Concepts
- Agent as a user
- A program that acts on the platform for a person: opens pull requests, deploys, reads logs. It has problems like any user (it guesses how to build a repo) and needs the same paths.
- Non-human identity
- The agent acts as itself (
agent:checkout-coding), never with a developer's personal token. Then its access can be limited, its actions audited, and its token revoked without locking anyone out. - MCP
- "An open-source standard for connecting AI applications to external systems" (modelcontextprotocol.io). A platform capability with an MCP interface can be called by an agent as a tool.
- AGENTS.md
- "A README for agents" (agents.md): one Markdown file in a repository that tells coding agents how to build, test and change it, and what they must not do.
- Default deny, approve at risk
- An agent may do only what the policy lists. Reading is cheap to allow; anything that changes production needs a person who says yes.
The same platform for a person and for an agent
| Need | A developer | A coding agent |
|---|---|---|
| Who it is | Their own account, from the identity provider | Its own non-human identity, owned by a team |
| How it reaches the platform | Portal, CLI, Git | API, MCP, Git, CLI. It cannot click a portal |
| How it learns the path | Docs, a colleague, the template | AGENTS.md in the repository, kept with the template |
| What it may do | Their team's role | A list per environment, default deny; prod writes need approval |
| What it may spend | Their team's budget | A monthly budget per agent |
| How it is held to account | Audit log, their name on the change | Audit log with the agent and the person it acts for |
Excessive agency, and the field that limits it
| Cause (OWASP LLM06:2025) | What it looks like | In agents/policy.yaml |
|---|---|---|
| Excessive functionality | The agent has tools it does not need for the job | allow: only the actions listed, per environment |
| Excessive permissions | The tools can do more than the action needs, often with a person's token | identity: its own, scoped; default: deny |
| Excessive autonomy | High-impact actions without a person to confirm them | approval: human on any prod action that is not a read |
Causes from OWASP LLM06:2025 Excessive Agency.
Files to know
Open them in your editor or on GitHub; the bullets say what to look at.
agents/policy.yaml(reference, your repo): The finished agent policy.golden-paths/new-service/AGENTS.md(reference, your repo): What agents read in every repository made from the path.capabilities.yaml(reference, your repo): The map after this module.
Steps
1. Add the agent as a user
The coding agents team-checkout uses are users with problems of their own. The evidence came from review comments and a token audit.
cd ~/platformengr/platform-design
Add to platform.yaml under users:, after the team-lead user
- id: coding-agent
kind: agent
who: Coding agents that open pull requests for product teams, in the IDE and in CI
problems:
- problem: Agents guess how to build and deploy each repo, and get it wrong in different ways.
evidence: Review comments on agent pull requests in team-checkout over one month
- problem: The only way an agent can act today is with a developer's personal token.
evidence: Token audit by the security enabling team
Expect ok platform.yaml:
npm run check
2. Open the capabilities agents need
Replace the map with the version for people and agents. What changed: most capabilities now list agents as users and have an mcp or api interface; AGENTS.md becomes a capability of its own (agent-instructions); agent identity moves from planned to beta. Cost stays for humans: an agent does not need to read the bill.
Replace the whole file capabilities.yaml
# What the platform offers, by layer, who owns it, and how people and agents reach it.
# Owner: the platform team. Read by the design check (rules C1 to C3).
# status: offered (supported today), beta (usable, may change), planned (not yet: nothing may depend on it).
capabilities:
# interfaces: how users reach the platform
- id: service-catalog
name: Service catalog and ownership
layer: context
owner: platform
status: offered
interfaces: [portal, api, mcp]
users: [humans, agents]
- id: agent-instructions
name: AGENTS.md and skills in every golden-path template
layer: context
owner: platform
status: beta
interfaces: [git]
users: [humans, agents]
# delivery and verification
- id: repo-template
name: New repository from a template
layer: delivery
owner: platform
status: offered
interfaces: [portal, cli, api]
users: [humans, agents]
- id: ci-pipeline
name: Build, test and scan on every pull request
layer: delivery
owner: platform
status: offered
interfaces: [git]
users: [humans, agents]
- id: preview-environments
name: A preview environment per pull request
layer: delivery
owner: platform
status: beta
interfaces: [git, api]
users: [humans, agents]
- id: deploy
name: Deploy through Git, with progressive rollout and rollback
layer: delivery
owner: platform
status: offered
interfaces: [git, api, mcp]
users: [humans, agents]
# runtime and data
- id: team-namespace
name: A namespace with quota and access per team and environment
layer: runtime
owner: platform
status: offered
interfaces: [git, api]
users: [humans, agents]
- id: postgres
name: A managed Postgres database
layer: runtime
owner: platform
status: planned
interfaces: [ticket]
users: [humans]
# agent control plane and model gateway
- id: agent-identity
name: An identity per agent, with scoped tokens and audit
layer: agent-control
owner: platform
status: beta
interfaces: [api]
users: [humans]
- id: model-gateway
name: One gateway for model calls, with budgets per team
layer: model-gateway
owner: platform
status: planned
interfaces: [api]
users: [humans, agents]
# observe, cost and trust
- id: logs-and-metrics
name: Logs, metrics and dashboards per service
layer: observe-cost-trust
owner: platform
status: offered
interfaces: [portal, api, mcp]
users: [humans, agents]
- id: cost-report
name: Cloud and AI cost per team and per change
layer: observe-cost-trust
owner: platform
status: beta
interfaces: [portal, api]
users: [humans]
Expect ok capabilities.yaml. Rule C3 checked that every capability for agents has an interface a program can call.
npm run check
Expect nine: the capabilities agents can use.
grep -c "users: \[humans, agents\]" capabilities.yaml
3. Put AGENTS.md into the golden path
The path gets a second kind of user. Agents read a file, so the path names the file, and the template copies it into every new repository.
Create golden-paths/new-service/AGENTS.md
# AGENTS.md: services made from the new-service golden path
This file is copied into every repository made from the `new-service` template. Coding agents read it before they
change anything. Owner: the platform team (the template); the product team (their copy).
## Build and test
- Install: `npm ci`. Test: `npm test`. Both must pass before you open a pull request.
- Do not add a dependency without saying why in the pull request description.
## Where things are
- `src/`: the service. `deploy/`: what the platform deploys. Do not edit `deploy/` by hand; change `service.yaml`.
- Who owns this service: the `owner` in `catalog-info.yaml`. Ask that team, not the platform team, about behaviour.
## What you may do
- Open pull requests. Never push to `main`, never merge, never change a workflow under `.github/`.
- Deploy to dev happens on merge. A deploy to prod needs a person to approve it; do not try another way.
- Use the platform's MCP tools for the catalog, logs and metrics. Use no personal tokens.
## When you are stuck
- Say so in the pull request. Missing context here is a platform gap: label the pull request `platform-gap`.
Change in golden-paths/new-service.yaml
- for: [humans]
+ for: [humans, agents]
Change in golden-paths/new-service.yaml
- support: "#platform-help, answered within one working day"
+ support: "#platform-help, answered within one working day"
+ agentInstructions: golden-paths/new-service/AGENTS.md
Expect ok golden-paths/new-service.yaml. Rule G5 checked that the AGENTS.md exists and that every step is on a capability agents can use.
npm run check
4. Write the agent policy
Two agents: team-checkout's coding agent, and the platform team's triage agent that only reads. Read each field as you type it, with the three causes of excessive agency in mind.
Create agents/policy.yaml
# Agents are users of the platform, with their own identity and limits.
# Owner: the platform team, with the security enabling team. Read by the design check (rules A1 to A7).
# An agent may do only what is listed here (default: deny).
default: deny
agents:
- id: checkout-coding-agent
owner: checkout
identity:
kind: non-human
name: agent:checkout-coding
actsFor: The developer in team-checkout who assigned the task
budget:
monthlyEur: 400
audit: true
allow:
dev:
- action: read catalog
capability: service-catalog
- action: create repository from template
capability: repo-template
- action: deploy
capability: deploy
- action: read logs and metrics
capability: logs-and-metrics
prod:
- action: read logs and metrics
capability: logs-and-metrics
- action: deploy
capability: deploy
approval: human
- id: platform-triage-agent
owner: platform
identity:
kind: non-human
name: agent:platform-triage
actsFor: The platform team's on-call engineer
budget:
monthlyEur: 150
audit: true
allow:
prod:
- action: read logs and metrics
capability: logs-and-metrics
- action: read catalog
capability: service-catalog
Run the check. Expect ok agents/policy.yaml and All checks passed. The check also confirmed that platform.yaml has an agent user, that every rule names a capability agents can call, and that the one prod action that is not a read needs approval: human.
npm run check
Find the line that keeps the coding agent from deploying to prod on its own. Expect approval: human, once:
grep -n "approval:" agents/policy.yaml
5. Commit
Save it.
git add -A && git commit -qm "Agents as users: policy, AGENTS.md, agent capabilities" && git push -q
gh run list --workflow design-check --limit 1
Simplified for the course
The policy is a file the check reads. On a real platform the same rules are enforced where agents act: by the identity provider, the MCP or API gateway and the deploy pipeline. The file is the design those systems implement.
Two agents with fixed budgets. Teams with many agents set budgets per team in a model gateway (planned in this map) and attribute cost per task.
Approval is one word. In practice it is a step in the deploy pipeline or an approval inbox, with the approver's name in the audit log.
Break it on purpose: Just use my token
The coding agent waits a day for every prod approval. A senior developer in team-checkout, tired of it, gives the agent their own personal token "for now" and deletes the approval, since they would have approved anyway. Do this one, fix included: the next steps build on what the fix leaves in your repo.
You practise: seeing excessive permissions and excessive autonomy in a policy, and keeping the agent useful without them.
1. Break it
Change in agents/policy.yaml
- kind: non-human
- name: agent:checkout-coding
+ kind: personal-token
+ name: jordan@checkout
Delete from agents/policy.yaml
- approval: human
npm run check
2. What you see
Expected: ok agents/policy.yaml. You get: FAIL and two lines: [A3] about the identity and [A7] about prod. Read both, and ask what the developer was really trying to fix.
3. Fix it yourself
Put the agent back on its own identity with a human approval for prod deploys. Done when the check passes, and you can name one change that would make the approval wait shorter without removing it.
Hint 1
With the developer's token, whose access does the agent have, and whose name is on its actions in the audit log?
Hint 2
Restore kind: non-human with the agent's own name, and approval: human under the prod deploy rule. The real problem was the wait, not the approval.
The fix
The wait is a platform problem worth solving: an approval inbox, approvals by the owning team rather than the platform team, or progressive delivery so a prod deploy carries smaller risk and is quicker to approve. Removing the approval solves none of it.
Change in agents/policy.yaml
- kind: personal-token
- name: jordan@checkout
+ kind: non-human
+ name: agent:checkout-coding
Add to agents/policy.yaml under prod:, after capability: deploy
approval: human
npm run check
git add -A && git commit -qm "The coding agent acts as itself, and prod needs a person" && git push -q
After you fixed it: the five questions
- What failed?
- The agent policy. The agent acted with a person's full access and could change prod alone.
- How was it detected?
- By rules
A3andA7of the check, in the pull request, before the token was used. - Who responds?
- The platform team and the security enabling team, with team-checkout's lead.
- How is it corrected?
- Restore the agent's own identity and the approval; revoke the personal token if it was stored anywhere.
- How is it prevented?
- Make the safe way faster: an approval inbox and a target time for approvals, measured like any other wait.
Quiz
- Why should a coding agent never use a developer's personal token?
- Personal tokens expire too quickly for long agent tasks
- The agent gets all of that person's access, its actions look like theirs in the audit log, and revoking it locks the person out too
- Agents cannot store tokens securely, so the token would leak
- An agent may read logs in prod and deploy to dev freely. What should a prod deploy need?
- A human approval, because it changes production
- Nothing extra, if the same deploy already passed in dev
- A second agent to review the change before it deploys
- Agents in team-checkout keep getting the build command wrong. Where is the fix, in this design?
- A bigger model in the model gateway, so the agent can work it out
- More permissions, so the agent can try more commands until one works
- The AGENTS.md in the golden-path template: the agent reads it before it acts
Answers
- The agent gets all of that person's access, its actions look like theirs in the audit log, and revoking it locks the person out too Its own identity can be scoped, audited and revoked on its own.
- A human approval, because it changes production Reads are cheap to allow; prod writes are where excessive autonomy hurts.
- The AGENTS.md in the golden-path template: the agent reads it before it acts Missing context is a platform gap; AGENTS.md is the context agents read.
Field note
Every team I have seen with an agent incident had the same root cause: the agent used a person's credentials. None of them had decided that. It happened one token at a time, to save a wait. Writing the policy down is how you notice the wait is the thing to fix.