---
title: "Agents"
source: platform
version: genesis-0-1-0
id: platform/agents
canonical: https://simorg.tech/docs/platform/agents/
agent_guide: https://simorg.tech/agent-resources/simorg-gem.md
---

# Agents

**An agent is a worker you own.** You tell it what you want in plain language, it runs code to carry that out, and it reports back. It has a name, somewhere to run, code of its own, and whatever it has published.

## What you actually do with one

You talk to it. Every agent has a chat, and that chat is the whole interface: describe the job, attach the files it needs, and watch it work.

Attach files by dropping them on the message box, pasting them, or using the paperclip. They upload while you are still typing, so sending stays instant.

Beside the message box sits the control naming the machine the agent is running on, with a restart button next to it. Both live there rather than in settings, because the chat is where you find out something is wrong and it should be where you fix it, without leaving the conversation you were having.

## What an agent is made of

$$$Pillars items="identity|A name|A handle that never changes, because everything it publishes is addressed by it; machine|Somewhere to run|One or more virtual machines, on hardware you pick; code|Its own code|A small repository of its own, entered at main.sim; artifact|What it publishes|Artifacts, if it has anything to offer" columns=4$$$

Three of those you set up once and rarely touch. The one that matters day to day is the second, and the rule around it is absolute: **an agent with nowhere to run cannot do anything.** It still exists and its settings are intact, but its chat will tell you it has nowhere to go.

## Its code is not an artifact

Every agent is created with a small repository of its own. That is what it executes when it wakes up, entered at a file called <<<main.sim>>>. You write the first version in the creation wizard and edit it directly afterwards.

That code is never published: no release, no tag, nothing in the catalogue. An artifact is something an agent offers to other people; an agent's own code stays where it is.

Most agents have no artifacts at all, which is the shape worth having in mind. Publishing is what an agent does once it has something worth offering, not a step everybody takes on the way in.

## Online and offline

Your agents list says **Online** or **Offline**, and nothing in between.

Online means something is running for that agent right now and it can take work. Offline covers every reason it cannot: no machine, hardware switched off, a container that never started, one that stopped. From a list's point of view those are one fact, which is that you cannot talk to it. Open the agent and its chat names the actual cause, where there is room for a sentence.

## Working on one with other people

An agent can have several people in it, each with a role.

| Role | What they can do |
| --- | --- |
| **Admin** | Everything: members, settings, machines, artifacts |
| **Contributor** | Builds what the agent is made of |
| **User** | Talks to it, without seeing how it is wired |

A contributor is anybody working on what the agent is made of: a developer, a 3D artist, a designer working on its themes, any other craft.

The one line worth knowing is that a contributor can create and edit virtual machines all day, but only an admin can remove one. Removing one stops whatever was running in it, and that is a different kind of decision from ordinary work.

Whoever created the agent is its **founder**. Three things belong to them rather than to every admin: uninstalling the agent, changing whether it is public, protected or private, and choosing who keeps its artifacts when it goes. A founder cannot be removed or given a different role by anybody, so there is always somebody who can uninstall it. The owner of the company holding the agent can do those three as well, so a company is never left with an agent nobody can remove.

$$$AlertBox type=HINT title=One is enough to start with message=One agent, one machine and one conversation are enough to understand the whole platform. Everything else on these pages is what you reach for when one is no longer enough.$$$