PlatformEngr® Platform fundamentals course

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.yaml has a third user, coding-agent, of kind agent. Nine capabilities list agents as users. The path is for: [humans, agents] and names golden-paths/new-service/AGENTS.md. agents/policy.yaml passes 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

NeedA developerA coding agent
Who it isTheir own account, from the identity providerIts own non-human identity, owned by a team
How it reaches the platformPortal, CLI, GitAPI, MCP, Git, CLI. It cannot click a portal
How it learns the pathDocs, a colleague, the templateAGENTS.md in the repository, kept with the template
What it may doTheir team's roleA list per environment, default deny; prod writes need approval
What it may spendTheir team's budgetA monthly budget per agent
How it is held to accountAudit log, their name on the changeAudit 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 likeIn agents/policy.yaml
Excessive functionalityThe agent has tools it does not need for the joballow: only the actions listed, per environment
Excessive permissionsThe tools can do more than the action needs, often with a person's tokenidentity: its own, scoped; default: deny
Excessive autonomyHigh-impact actions without a person to confirm themapproval: 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.

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 A3 and A7 of 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

  1. 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
  2. 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
  3. 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
  1. 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.
  2. A human approval, because it changes production Reads are cheap to allow; prod writes are where excessive autonomy hurts.
  3. 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.

Report a problem with this module