> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komodor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent identity

> Every agent is a governed principal with its own credential and permissions, enforced where the action lands rather than inside the agent.

An agent is a first-class identity, alongside people and service accounts. It acts under its own
name, holds its own permissions, and belongs to exactly one workspace. This page explains how a
worker proves which agent it is, why the credential rather than the name is what is trusted, and how
you rotate or revoke that credential.

## An agent as a principal

Every run, log line, and piece of evidence an agent produces is attributed to **the agent**, not to
whoever triggered it. That is what makes an agent's history reviewable: you can ask what this agent
has done, and get an answer that is not tangled up with the people who invoked it.

When an agent registers it is granted the built-in **Agent** role — a least-privilege default that
deliberately excludes the credential-minting actions an autonomous worker must never hold. That is
the role every agent holds unless you narrow it. You manage an agent's roles from
**Settings → Agents**, with the same model used for members; see
[Roles & permissions](/security-and-governance/identity-and-access/roles-permissions).

## Name and identity are different things

An agent has a friendly name — its slug, something like `triage` — which is what you see in the
console and in URLs. That name only has to be unique inside your workspace, so two workspaces can
each run a `triage` agent with entirely separate identities and no way to detect one another.
Underneath, each agent has a stable opaque identity that the platform uses to attribute work and
enforce isolation.

## How a worker authenticates

An agent runs as a **worker** — one process hosting one agent. The worker authenticates with a
**worker token** issued for that specific agent, and sends its friendly name alongside it.

<Note>
  **The token is what is trusted.** The platform resolves the agent and its workspace from the token
  itself, then checks that the name presented matches the agent the token belongs to. A valid token
  presented with the wrong name is rejected — so a worker can never act as another agent, and never
  reaches another workspace's data.
</Note>

You do not assemble any of this by hand. The SDK attaches the credential to registration, heartbeat,
run-claim, and evidence requests for you.

## Configuring a worker

The SDK reads the worker's identity and its target control plane from the environment:

| Variable                | Required | Purpose                                                                                                                                                                                |
| ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AGENTOPS_URL`          | Yes      | The control plane the worker talks to.                                                                                                                                                 |
| `AGENTOPS_WORKER_TOKEN` | Yes      | The worker token it authenticates with.                                                                                                                                                |
| `AGENTOPS_AGENT_ID`     | No       | Overrides the agent's friendly name. Set it only when one generic worker image has to adopt a per-deployment identity — the token must be bound to whichever name the worker presents. |
| `AGENTOPS_WORKER_ID`    | No       | An optional identifier for this worker process.                                                                                                                                        |

## Managing a worker token

A token is minted when the agent is created and delivered to the worker as a secret — an environment
variable or a mounted secret. Keep it out of source control.

Every self-deployed worker authenticates with a revocable token bound to its agent, managed from
**Settings → Agents → Worker tokens**. Tokens for agents that have not registered yet are listed
too, so a token can be prepared before its worker comes online. **The value is shown only once**,
when it is issued or rotated:

<Steps>
  <Step title="Check its status">
    Whether a token exists, when it was created or last rotated, and when it expires.
  </Step>

  <Step title="Rotate">
    Mints a replacement and stops the old value working, so update the worker's secret as part of
    the same change.
  </Step>

  <Step title="Revoke">
    Immediately stops any worker using that token. Revocation needs no redeploy.
  </Step>
</Steps>

Token creation and revocation are both recorded in the
[audit log](/security-and-governance/controls/audit-log).

## Next steps

<CardGroup cols={2}>
  <Card title="Access explorer" href="/security-and-governance/identity-and-access/access-explorer">
    Ask what one agent is actually able to do.
  </Card>

  <Card title="Agent isolation & tenancy" href="/security-and-governance/architecture-considerations/agent-isolation-tenancy">
    How one agent is kept away from another's data.
  </Card>

  <Card title="Standards & Guardrails" href="/security-and-governance/controls/standards-guardrails">
    The runtime checks an agent's actions cross.
  </Card>

  <Card title="Secrets & credential handling" href="/security-and-governance/architecture-considerations/secrets-credential-handling">
    How a credential reaches a run without being exposed.
  </Card>
</CardGroup>


## Related topics

- [Access explorer](/security-and-governance/identity-and-access/access-explorer.md)
- [Service accounts](/security-and-governance/identity-and-access/service-accounts.md)
- [Roles & permissions](/security-and-governance/identity-and-access/roles-permissions.md)
- [Control plane](/get-started/architecture/control-plane.md)
- [Python SDK](/developer-tools/python-sdk.md)