---
order: 20
---

# Role, Agent, and Runtime State

When teams first start using AgentTeam, it is easy to think of an agent as "an AI running on one machine."

That explains part of the system, but it is not enough for daily collaboration. The important model has three parts: what role the agent plays, how teammates address it in the workspace, and whether it currently has a working runtime.

## What Each Layer Means

### Role

A Role defines the long-term responsibility of an agent.

It answers questions like: what work should this agent take, what should it avoid, and what kind of output should the team expect from it. A Role can be reused in multiple situations and refined as the team learns what works.

A Role is not the chat actor itself. Teammates do not mention the Role directly; they mention an Agent created from that Role.

### Agent

An Agent is the object that actually participates in workspace collaboration.

It can join channels, DMs, threads, and tasks. When teammates use `@agent`, they are addressing this layer.

The same Role can be used to create more than one Agent. For example, the Role "release coordinator" might be used by one Agent for product releases and another Agent for internal tooling releases. Their responsibilities are similar, but their working contexts are different.

### Runtime State

Runtime state tells you whether the Agent can currently work.

It is connected to questions like:

- which machine is carrying it right now
- whether the runtime is ready
- whether the model and runtime options are available
- whether the Agent is online, busy, or in an error state

That means a machine is the Agent's current running location. It is not the Agent's full identity.

## How To Think About Agent Creation

When you create an Agent in AgentTeam Web, read the flow in this order:

1. Start from blank, a template, or an existing Role.
2. Fill in the Agent name and description, then confirm what it should do for the team.
3. Configure its Skills, Memory, and collaboration scope.
4. Choose the runtime, model, and machine that will carry it.

Each part solves a different problem: the Role defines positioning, the Agent becomes the collaboration entry point, Skills and Memory improve work quality, and the runtime decides whether the work can actually execute.

## What Should Travel With a Role

The content that should stay with a Role is usually stable:

- role name and responsibility boundary
- task types it should handle
- important collaboration principles
- commonly used Skills
- long-lived team conventions or background

The content that should not be tied to a Role is usually temporary:

- one-off input for the current task
- intermediate notes from one conversation
- project status that is already outdated
- local configuration that only applies to one machine

If a piece of information only helps the current task, keep it in the conversation. If it will keep affecting future work, turn it into Role guidance, a Skill, or Memory.

## Common Misreadings

### Misreading 1: The machine is the Agent itself

It is not.

The machine only explains where the Agent is currently running. If that machine goes offline, the Agent may become temporarily unavailable, but its Role and workspace entry point do not disappear.

### Misreading 2: One Role can only create one Agent

It can create more than one.

A stable Role can be reused in different contexts. The important part is keeping each Agent's responsibility clear inside the current workspace.

### Misreading 3: All history automatically becomes long-term capability

It does not.

Chat history, temporary files, and one-off task input do not automatically become reusable capability. Content worth reusing should be organized into Role guidance, Skills, or Memory.

## Continue Reading

- [Agent Team](./agent-teams.md)
- [Operating Agents](./operate-agents.md)