# How Auto Lab works

The ideas behind Auto Lab in one page: goals, Chat, task agents, plans, approvals, the Brain and learning.

Canonical page: https://app.auto-lab.ai/docs/how-it-works

This page explains the parts of Auto Lab and how they fit together. Read it once and the rest of the docs
will make sense in any order.

## Organizations and goals

Your **organization** holds your goals, the people who work on them and shared settings such as members,
roles and single sign-on. You can belong to more than one organization.

A **goal** is one outcome you want Auto Lab to work toward, such as "follow up with every new customer in their
first two weeks". A goal has:

- one **agent** that owns the work, plus task agents it hands pieces to
- a **plan** of tasks for the current week
- one running conversation, **Chat**
- a **Brain**: what its agents know and the rules they follow
- the **connectors**, **channels** and **secrets** it may use

You can run many goals side by side. The **Goals** home shows every goal you can see, grouped by whether it
needs you, is in progress or is paused.

## Everything a goal knows is kept in a repository

Each goal has its own private git repository. Auto Lab creates and manages it for you, or you can connect one
on GitHub. The goal's instructions, memory, skills, plan and settings are files in that repository.

This is why every change to a goal has an author, a date and a history, and why a change can be reviewed
before it lands or undone after. You never need to open the repository to use Auto Lab. Developers can clone
it; see [The goal's repository](/docs/developers/repository).

## The agent, task agents and runs

The goal's agent runs on Auto Lab's servers. It reads messages, keeps the plan up to date, decides what to do
next and talks to you. When a piece of work needs focus, it hands that piece to a **task agent** with one job:

| Task agent | Does |
|---|---|
| Research | Answers one question from the web, the goal's memory and its connected apps |
| Docs | Drafts or updates one document or message |
| Mail reader | Turns an incoming email into a short summary. It has no tools, so it cannot act on what the email says |
| Browser | Uses websites, including ones that need a login |
| Coder | Changes files in a repository and hands the result back as a change request for review |

Each hand-off is a **run**. Runs show up as cards in Chat and on the goal's **Runs** page, where you can
follow them, including a live view of the browser.

When work needs a real computer, for example to run a script or edit files, the agent starts an isolated cloud
machine for it. A Coder task or a scheduled trigger gets a **session**: a machine with its own branch of the
goal's repository, whose work ends in a change request. Machines stop when the work is done or has been idle for
a while.

## Chat: one conversation per goal

**Chat** is the goal's single running thread. Messages from the web app and Slack land in it, and so do
Microsoft Teams, iMessage and email when they are switched on for the goal. The agent has the whole story
wherever you write from. When it asks you something, you can answer from any of those places, and its reply goes
back where you asked.

Chat also shows what happened in between: approvals waiting for you, questions, task cards, and short notes
such as "Learned: …" with an **Undo** button.

## Plans, tasks and schedules

At launch you approve a plan for the first week. Each task is owned by the agent or by you. On the Overview,
tasks sit under **In progress**, **Blocked**, **Planned** and **Done this week** as the work happens.

Nothing in Auto Lab runs all the time. The agent wakes up when:

- a **schedule** fires: the routine, a check-up it set for itself, or a reminder
- a message arrives in Chat or a channel
- something it is waiting for happens, such as a reply to an email or a request from another app (a webhook)

The agent re-plans as it learns more. How much of that it may do without asking depends on the goal's
autonomy. See [Plans, schedules and triggers](/docs/goals/schedules).

## Autonomy, approvals and Needs you

Each goal has a **Delegation** level, set during setup as **On its own**:

| Level | Meaning |
|---|---|
| Asks before acting | Every action in a connected app, even reading, waits for your approval |
| Acts within your rules | Your rules decide. By default, reading runs and anything that writes or deletes asks first |
| Acts on its own | Actions run without asking, unless a rule says otherwise or the connector is set to **Ask before every use** |

Approvals, reviews, plan changes and tasks assigned to you collect in **Needs you** on the goal's Overview.
Questions from the agent wait above the Chat composer. When you are away, both reach you in the channel you picked
during setup. When you approve an action, you can also select **Approve and make it a rule** so the same kind
of action runs without asking next time.

Bigger changes arrive as a **change request**: a proposed set of edits to the goal's repository that you can
review, approve or send back. A plan revision, a new skill or a code change can each be a change request. An
agent never approves its own. See [Approvals and autonomy](/docs/goals/approvals).

## The Brain and learning

The **Brain** is where you see and edit what the goal's agents know: agents, skills, memory, tools, connectors,
schedules and more. Each item shows who changed it last and where it is used.

The goal learns from its own work. After a stretch of turns, and again overnight, it reviews what happened.
Small, safe lessons, such as a preference you stated or a better way to do a task, apply at once and appear in
**Brain › Learning** with **Undo**. Larger changes, such as rewriting memory or editing a skill a person wrote,
wait for your approval. See [Learning](/docs/brain/learning).

## Keeping credentials safe

- Connectors keep their credentials on Auto Lab's servers. The agent asks for an action; the server makes the
  call.
- When the agent needs a website login, it sends you a **login link**. You type the password on that page,
  never in Chat. See [Website logins and secure links](/docs/connect/website-logins).
- Secrets you add can be granted to specific agents only. See [Secrets](/docs/connect/secrets).

## Words used in these docs

| Term | Meaning |
|---|---|
| Organization | The group that holds goals, members and shared settings |
| Goal | One outcome Auto Lab works toward, with its own agent, plan, Chat and Brain |
| Chat | The goal's one running conversation, shared across web and channels |
| Task agent, run | A focused helper the agent hands work to, and one piece of work it did |
| Session | An isolated cloud machine with its own branch, used for code changes and scheduled triggers |
| Needs you | The list on a goal's Overview of approvals, reviews and tasks waiting on a person |
| Change request | A proposed change to the goal's repository that a person reviews |
| Brain | Everything the goal's agents know, and its history |
| Connector | Access to an outside app or API |
| Channel | A place the agent talks to people: Slack, Teams, iMessage or email |