# Agents and identity

In AgentOS an agent is treated like an employee. It has an identity, so you always know who it is, who it works for, and what it may do.

## The agent profile

Every agent has:

- A handle: a unique short name such as inbox-helper. It uses lowercase letters, numbers and dashes, starts with a letter, and is 3 to 30 characters long.
- A job title, for example "Interview scheduler".
- A short bio that describes what it does.
- A workspace: the team it belongs to.
- A status: active or suspended.

A handle is created for you when the agent is saved. Admins can change the handle, title and bio on the agent's page under Identity. Handles are unique across AgentOS, so a handle that is already taken is refused.

## Suspend and reactivate an agent

Open the agent and choose Suspend this agent. A suspended agent cannot run anywhere: not from the console, not on a schedule, not from a deployment, and not through an API token. Choose Reactivate this agent to turn it back on. This is the fastest way to stop one agent without touching the others. To stop everything in a workspace at once, use the emergency pause described in Safety and privacy.

## Who can change what

Workspace roles are owner, admin and member. Members can view agents and start runs. Admins and owners can create agents, edit profiles and permissions, connect services, deploy and publish. Only an owner can make another person an admin or owner.

## Agent tokens: let your own software act as an agent

An agent token lets a program of yours start runs as one specific agent through the API.

1. Open the agent and go to API tokens.
2. Give the token a label such as "my server" and choose Create token.
3. Copy the token immediately. It starts with aos_ and is shown only once. AgentOS stores only a fingerprint of it.

Send it as a Bearer token. To start a run:

```
POST /agent-api/run
Authorization: Bearer aos_your_token
Content-Type: application/json

{"input": "Check my inbox for urgent mail", "dry_run": true}
```

The default is a practice run (dry_run true). With dry_run false it is a real run, and anything that sends or changes something still waits for approval. GET /agent-api/me returns the agent's profile. An agent can have at most 10 live tokens. Revoke a token from the same screen and it stops working at once. Suspending the agent also stops all of its tokens.