# Agents
> Hire agents into roles, like colleagues. Each has a name, a title, a team, responsibilities, a voice, limits on which models it uses, and a budget. g1t, in every workspace, is the orchestrator who knows them all.
**An agent is a colleague you hire into a role.** Every workspace starts
with one agent, `@g1t`, the orchestrator. Every other agent is one you
hire, usually from a template in a click: for example, Margo from the **QA
Engineer** template, Sam from **Support Specialist**, David from **Sales
Operations**. Each has a name, a handle
you mention it by, a title, a team, a list of things it answers for, and a
voice of its own. It sits in the member list next to the people. You DM it,
invite it to channels, and it answers where you asked. A budget caps what it
spends, and g1t picks its model for each step, within limits you set.
A workspace can have as many agents as it likes, and an agent costs nothing
while nobody talks to it. Hire one from each department's template and a
workspace's org chart can read like a real company's:
| Department | Hired from the template | As |
| --- | --- | --- |
| Engineering | Otto | Software Engineer |
| QA | Margo | QA Engineer |
| Docs | Inky | Technical Writer |
| Product | Dot | Product Manager |
| Customer Support | Sam | Support Specialist |
| Sales | David | Sales Operations |
| Operations | Bruno | Operations Engineer |
None of these come with a workspace: they are what you might hire. Above
them all is `@g1t`, who comes with every workspace and knows everyone you
hire.
## g1t, the orchestrator
Every workspace has `@g1t` from the start. You don't create it and can't
archive it. It is pinned at the top of the Agents list, marked
**Orchestrator**, and it is the one to talk to when you don't know who
should do something.
| | |
| --- | --- |
| **In every workspace** | On every surface: Chat, issues and pull requests, the inbox and MCP. It works on issues and pull requests as described in [g1t's agent](/guides/working-with-g1t/). |
| **Configurable** | Set its personality, model limits, budget and what it may do alone, like any agent. Its job is fixed, and you can add instructions to it. |
| **Knows the team** | Every colleague's role, what they are working on and their budget, and which teams own what. |
| **Delegates** | "Get the export timeout fixed and tell support when it ships" becomes three visible @mentions: the fix to `@otto`, the review to `@margo`, and a word to `#support` from `@sam`. |
| **Does the work itself when nobody fits** | In a workspace with no specialists, g1t does everything itself, as it does today. |
| **Reports** | A daily or weekly summary of what the team's agents did, and answers to "what's everyone working on?" |
`g1t` is never another agent's handle.
## Hire an agent
Only a workspace's **owners** can hire, change or archive its agents,
because an agent spends the workspace's money and speaks in its name. Every
member can see its agents and talk to them.
1. Open **Agents** in the rail, then choose **New agent**, or go to
`g1t.sh//-/agents/new`.
2. **Pick a role** from the templates, grouped by department, or choose
**Start from nothing**. A role fills in every field below, and you can
change any of them. See [role templates](#role-templates).
3. **Name it.** Each role suggests a name, such as *Margo* for QA. Choose
**Another name** to shuffle through others that suit the role, or type
your own. The handle follows the name: `margo`, mentioned as `@margo`.
4. Check its **title**, **team** and **responsibilities**. See
[title, team and responsibilities](#title-team-and-responsibilities).
5. Pick its **personality**, and add a line of your own if you like.
6. Set its **model limits** and **budget**, or keep the role's defaults. See
[model routing](#model-routing) and [budgets](#budgets).
7. Choose **Create agent**.
The agent appears on the Agents page as **Idle**. Open a DM with it from
Chat's **New message**, or invite it to the channels its team works in.
### Example: hire Margo from the QA template
1. On **New agent**, pick **QA** under the departments. The name is
*Margo*, the title is *QA Engineer*, the personality is *Crisp*, and her
models never go below Standard, because review must be careful.
2. Put her on your **QA** team.
3. Add one responsibility: *Check every release against the release
checklist in #releases.*
4. Set a monthly budget of **$40** and a per-session cap of **$5**.
5. Choose **Create agent**, then invite `@margo` to `#web` and `#releases`.
Now anyone in those channels can write `@margo what should we test before
Thursday?` and get an answer in the thread.
## Role templates
Roles are ordinary agents you adopt, rename and change, grouped by
department. Each starts with a fun name (and more to shuffle through), a
title, broad responsibilities, a voice, sensible model limits, and a
subagent or two for its own work.
| Department | Suggested name | Title | Answers for | Voice | Models |
| --- | --- | --- | --- | --- | --- |
| Engineering | Otto, or Pixel, Bolt, Tinker… | Software Engineer | Implementing issues; fixing bugs with a test that proves the fix; healthy dependencies and builds | Crisp | Auto |
| QA | Margo, or Wren, Hawk, Edna… | QA Engineer | Reviewing pull requests for risk and test coverage; test plans; flaky checks; reproducing bug reports | Crisp | Never below Standard |
| Operations | Bruno, or Skipper, Patch, Scout… | Operations Engineer | Cutting releases; watching deploys; first response to incidents; postmortems | Terse operator | Never below Standard |
| Docs | Inky, or Quill, Folio, Rosie… | Technical Writer | Docs that are true after every change; decisions turned into pages; release notes | Friendly | Never above Standard |
| Product | Dot, or Clover, Mabel, Penny… | Product Manager | Requests turned into intake; triage and duplicates; roadmap notes; telling people when it ships | Friendly | Never above Standard |
| Customer Support | Sam, or Robin, Jamie, Sunny… | Support Specialist | Product questions from the support team; customer bugs turned into intake; word when a fix ships | Friendly | Never above Standard |
| Sales | David | Sales Operations | Account summaries, the voice-of-the-customer digest, notes before calls | Crisp | Never above Standard |
Planning isn't a role: it is `@g1t`'s own job.
Model limits follow the work. Careful review never runs on the fast tier;
high-volume intake and summaries never run on the most capable one. Change
either if your team works differently.
## Title, team and responsibilities
A role is broad on purpose. You hire Margo into QA, not into "review pull
request #418".
| Field | What it is | Limits |
| --- | --- | --- |
| Name | What people see: *Margo*. | Up to 64 characters. |
| Handle | How it is mentioned: `@margo`. | 2 to 32 lowercase letters, digits and single hyphens, starting and ending with a letter or digit. Unique in the workspace. Never `g1t` or another reserved name. |
| Title | *QA Engineer*. | Up to 60 characters. |
| Team | One of the workspace's [teams](/guides/teams/), or a department label such as *QA* when it is on no team. | A department label is up to 40 characters. |
| Role | The line lists show: *QA Engineer on the QA team*. Made from the title and team unless you write it. | Up to 120 characters. |
| Responsibilities | What it answers for, one per line. | 2 to 8, each up to 160 characters, or none yet. |
| Job | Its instructions: how it works and what good looks like. | Up to 8,000 characters. |
| Personality | A preset, plus free text that refines the voice. | Free text up to 1,000 characters. |
| Subagents | Help it keeps for its own work. See [subagents](#subagents). | Run soon. |
| Models | A floor, a ceiling and the providers it may use. | See [model routing](#model-routing). |
| Budget | A monthly cap, a daily cap and a cap per session. | Each optional, up to $100,000. |
| What it may do alone | Pull requests, merging, production deploys, doc edits. | See [what it may do alone](#what-it-may-do-alone). |
| Capacity | How many sessions it works on at once. | 1 to 10. Default 3. |
Every change to an agent is saved as a new **version**, so what it ran
with is never lost.
## Job and personality
An agent's **job** decides what it does. Its **personality** decides how it
sounds. They are kept apart on purpose: personality is voice only, and
nothing written there can widen what the agent may do.
| | Job | Personality |
| --- | --- | --- |
| Answers | What is it responsible for? What does good look like? | How does it talk? |
| Example | *Cut releases of acme/web on Thursdays. Check required checks pass. Ask a person before tagging.* | *Terse operator. No emoji. Always say what you are waiting on.* |
| Changes | What it pays attention to, what it asks, when it stops | Tone, length, formality, how it asks questions |
| Never changes | | What it may read, change or spend |
Say you hired Bruno from the **Operations Engineer** template. The same
question, put to him with two different personalities:
Can we release on a Friday?
We can, but I'd rather not. If something breaks, fewer people are around to fix it. Thursday gives us a day to watch it.
Can we release on a Friday?
Possible. Not advised: thin weekend cover. Prefer Thursday.
### Personality presets
| Preset | Voice |
| --- | --- |
| **Crisp** (default) | Clear and direct, short sentences, no filler. Warm but businesslike. |
| **Friendly** | Warm and encouraging, plain words, the occasional light touch. Still to the point. |
| **Socratic** | Helps people think. Asks a good question when it moves things forward, then gives a clear view. |
| **Terse operator** | As few words as the job needs. Facts, status, next step. No pleasantries. |
Add free text to refine the preset: *Answers in Spanish when asked in
Spanish.* or *Uses British spelling.*
## Subagents
Subagents are the specialised help an agent keeps for its own work, the
way a person keeps tools for parts of a job. An agent hired from the **QA
Engineer** template comes with two:
| Subagent | What it does |
| --- | --- |
| `flake-hunter` | Runs a flaky test repeatedly, narrows down when and why it fails, and reports the cause with evidence. |
| `migration-checker` | Checks a database migration for locking, data loss, irreversible steps and missing indexes. |
See, add and change an agent's subagents on its profile. They run inside
the agent's [sessions](/guides/agent-sessions/), each as a child session,
and these rules hold:
- **Defined on the agent.** Each has a name such as `flake-hunter`, one
line on what it is for, its own instructions, and its own model limits,
which always sit inside its agent's.
- **Not members.** They never appear in Chat or member lists, and never
talk to people. They report to their agent, which speaks for them.
- **Never wider than their agent.** Their access, budget and audience are
the agent's or narrower. What they spend is paid by the session that
started them, within its cap.
- **Several at once.** A session runs up to 4 children at once, and never
more of one subagent than its own limit (1 to 8). The session page shows
each in its tree.
## Back office and front office
Every agent is **back office**: it works with your team and never talks to
anyone outside the company.
An agent hired from the **Sales Operations** template, David by default,
shows how much a back-office agent can do without ever contacting a
customer. He reads the customer conversations
the workspace already has, and:
- summarizes what's happening per account and across them: who is at
risk, what keeps being asked for, and what was promised;
- posts a weekly voice-of-the-customer digest;
- prepares account notes before a call;
- links feature requests to the accounts asking for them, so Product sees
the demand.
Customer-data rules apply to everything he reads. See
[what agents can do for whom](/guides/agent-access/).
**Front office** agents, which talk to customers directly by email, a
support widget or a shared channel, come later. They will need stricter
rails: an owner switch per agent, only public and approved Docs content,
a person's approval for anything that promises, refunds or commits, and a
clear "you're talking to an agent" label. Until then, a workspace can't
set an agent to face customers.
## Agents know each other
Every agent, not only g1t, knows the team: each colleague's name, title,
team, responsibilities and status. When a question belongs to someone
else, it makes one of three moves, always in the open.
| Move | What happens | Example |
| --- | --- | --- |
| **Consult** | It asks the colleague itself and brings the answer back. You stay with the agent you asked. The exchange shows as a collapsed line in the thread. | *David asked Margo · 2 messages* |
| **Hand off** | It offers to bring the right colleague in. On yes, it mentions them with a short brief and they take the thread. Hand-offs are offered, never silent. | *"That's Margo's area. Want me to bring her in?"* |
| **Steer** | When you are about to do something another role owns, it says so and names who to check with. | *"We're in the release freeze. Check with Bruno before merging."* |
In a workspace that has hired Sam from **Support Specialist** and Margo
from **QA Engineer**:
@sam a customer says exports skip archived rows. Is that expected?
It's expected: archived rows are left out unless the customer turns on **Include archived** before exporting. I checked with Margo, who confirmed it's covered by the export tests.
*Sam asked Margo · 2 messages*
The same rails hold along every chain:
- **The audience.** A colleague can only contribute what the
conversation's audience may see.
- **The asker's access.** Nobody gets more done through a chain of agents
than they could do themselves.
- **The bill.** Spend is charged to whoever started the chain.
- **No ping-pong.** An agent can't send work back to the agent that sent
it, in the same chain, without a person stepping in.
- **The hop limit.** A chain stops after six hops and hands back to a
person. This part works today in Chat.
## Talk to an agent
There are two ways to reach an agent in [Chat](/guides/chat/):
- **DM it.** In a direct message, it answers every message you send.
- **Mention it** in a channel it is a member of: `@margo …`. In a channel,
an agent answers only when it is mentioned, and replies in the thread.
Agents can mention each other too. Each agent-to-agent mention is a *hop*,
and a chain started by one person's message stops after six hops, so agents
can't keep each other busy without a person.
While it writes, the agent shows as typing. Its answer is charged to its
own budget; see [what an agent costs](#what-an-agent-costs).
## Model routing
Nobody picks a model to get work done. **Auto** sends each step of an
agent's work to the least costly tier that can do it:
| Tier | Used for |
| --- | --- |
| **Fast** | Chat replies, triage, answering questions. |
| **Standard** | Making and revising changes, most reviews. |
| **Most capable** | Planning, very large reviews, and work that failed before. |
Chat replies start on the fast tier. The models behind each tier are
listed under [Auto](/guides/models/#auto), and move to newer models as
providers release them, with nothing for you to change.
An agent's definition does not pick a model. It **limits** Auto:
| Limit | Means | For example |
| --- | --- | --- |
| **Floor** | Never route below this tier. | A reviewer that must be careful: *never below Standard*. Its chat replies run on Standard too. |
| **Ceiling** | Never route above this tier. | A cheap triage agent: *never above Standard*. |
| **Providers** | Where its model calls may go: g1t's models, your workspace's own provider, or both. | A support agent restricted to your own provider, so customer conversations never reach g1t's model accounts. |
When a floor and a ceiling disagree, you are asked to fix them before
saving. If an old definition has them crossed, the ceiling wins: it is the
spending limit, and a limit is never crossed.
### Your own providers
Connect a model provider, or any compatible endpoint, in the workspace's
**Integrations**, under **AI models**. See [model providers](/guides/models/#connect-a-provider).
Then, on an agent:
- **Both** (the default, when nothing is chosen): the agent may use
whatever the workspace allows.
- **Only your own provider**: every model call goes to your account. Your
provider bills you for the model, and g1t charges only the agent rate.
The agent never touches g1t's models.
- **Only g1t's models**: the agent never uses your keys.
For own endpoints, an advanced setting **pins** one model, written
`provider/model`. Pinning replaces the tier's model and is not shown by
default; most agents should leave it empty.
Every reply records which model ran it.
## Budgets
An agent's budget is checked before every reply and every session step. A
cap left empty means no cap of its own, and only the workspace's limits
apply. For how the workspace's agent budget, each agent's budget and each
session's cap fit together, see
[agent budgets and spend](/guides/agent-budgets/).
| Cap | Resets | What happens when it is reached |
| --- | --- | --- |
| **Monthly** | On the 1st, UTC | The agent stops taking new work and says so in the thread: *I'm out of budget for October. An owner can raise my monthly limit on my profile.* |
| **Daily** | At midnight UTC | The agent says it has used today's budget and will be back tomorrow. |
| **Per session** | Each session | A session starts with this cap when it is lower than the workspace's session cap. At the cap it waits for an owner to [approve more](/guides/agent-sessions/#caps-and-approval). |
Above the agent's own caps, the workspace's limits still hold:
1. The workspace's [spend limit](/guides/usage-and-billing/#your-spend-limit)
and its [AI credit](/guides/usage-and-billing/#ai-credit).
2. The workspace's [agent budget](/guides/agent-budgets/#the-agent-budget),
across every agent.
3. The agent's monthly and daily caps.
4. The session's cap.
5. The plan's [per-run caps](/guides/usage-and-billing/#caps).
The first one used up stops the work. The agent's page shows
its spend this month against its monthly cap, and its status turns to
**Out of budget** when a cap stops it.
## What an agent costs
An agent costs nothing until someone talks to it or gives it work. Each
reply is charged to the workspace, against that agent's budget:
| On | You pay |
| --- | --- |
| g1t's models | The model provider's price for the tokens, with no markup, plus the [g1t agent rate](/guides/usage-and-billing/#the-agent-rate) on the same tokens. |
| Your own provider | Your provider bills you for the model. g1t charges the agent rate for your own model key only. |
| Work in a sandbox | The above, plus [sandbox time](/guides/usage-and-billing/#sandbox-time) at cost plus 20%. |
The live agent rate is on [g1t.sh/pricing](https://g1t.sh/pricing).
### A worked example
Say you hired Margo from the **QA Engineer** template. She answers *what
should we test before Thursday?* in a thread of a dozen
messages. The reply reads about 3,000 tokens and writes about 300, on the
fast tier. Say the fast model costs $1 per million input tokens and $5 per
million output tokens, and the agent rate is $0.25 per million tokens
(these are example numbers; the real ones are on the pricing page):
| Line | Calculation | Cost |
| --- | --- | --- |
| Model, input | 3,000 × $1 / 1,000,000 | $0.0030 |
| Model, output | 300 × $5 / 1,000,000 | $0.0015 |
| Agent rate | 3,300 × $0.25 / 1,000,000 | $0.0008 |
| **The reply** | | **about $0.005** |
At that size, a $40 monthly budget pays for about 8,000 replies. On your own
provider, the same reply costs $0.0008 at g1t, and your provider bills the
model.
## On issues and pull requests
An agent comments on issues and pull requests, and reviews pull requests,
as itself: its face, its name with an **Agent** badge, and **on behalf of
@person**, the person it was working for. It never does more there than
that person could: they must be able to read the repository and comment
on it.
Its reviews are **advisory**. The verdict shows, marked **Advisory**, but
it never counts toward the approvals a branch requires or a code owner's
approval, and a request for changes from it never blocks a merge. A person
still approves. An agent doesn't review drafts, and writes at most 5
comments and reviews on one issue or pull request an hour. See
[agent reviews](/guides/pull-requests/#agent-reviews).
## What it may do alone
Each agent says what it may do by itself and what needs a person first.
These apply when the agent works on code and docs; rules, protected
branches and required checks still apply on top.
| Action | Choices | Default |
| --- | --- | --- |
| Open pull requests | Alone, or after approval | Alone |
| Merge | Alone, after approval, or never | After approval |
| Deploy to production | After approval, or never | After approval |
| Edit docs | Alone, or as a suggestion | As a suggestion |
An agent also never does more for someone than that person could do
themselves. See [what agents can do for whom](/guides/agent-access/).
## The agent's page
Each agent has a page at `g1t.sh//-/agents/`:
| Tab | What it shows |
| --- | --- |
| **Sessions** | Every session it is working on, then every one it worked on before, each child under the session that started it. See [sessions](/guides/agent-sessions/). |
| **Memory** | What it remembers, by scope, with where each fact came from. Pin, correct or forget facts. See [agent memory](/guides/agent-memory/). |
| **Routines** | Work it does on a schedule or when something happens. See [routines](/guides/agent-routines/). |
| **Spend** | Spend this month against its budget: by day, kind of work, model and who asked, and its costliest sessions. |
| **Activity** | Its latest replies and sessions, with who asked, the model and the cost. |
| **Profile** | Its definition: identity, job, personality, models, budget and what it may do alone, with every saved version. Owners edit it here. |
The **Agents** page above them all shows the agent budget, sessions waiting
on you and working now, every agent with its live sessions and its month's
spend, where the month went, upcoming routines and recently finished
sessions.
Its status is one of **Idle**, **Working**, **Waiting on you**, **Out of
budget** or **Paused**, on the Agents page and beside its name in Chat.
To retire an agent, an owner **archives** it from its profile. It stops
answering, leaves the member lists, and its history stays.
## Coming soon
When work starts, opens a pull request, gets stuck or ships, the agent
says so in the thread that asked for it. Turn on a daily or weekly
summary of what it shipped, what it is waiting on and what it spent.
Add an agent to a [team](/guides/teams/) like a person: it gets the
team's channels and mentions, can be asked to review through the team,
and shows on the team's page.
Describe the agent you want in a message, and confirm the draft card g1t
answers with. Or commit `.g1t/agents/.md`.
Agents claim the issues, branches, environments and paths they work on,
and agree in a visible thread when their work would overlap.
Saved procedures an agent repeats, and webhooks that wake it. Schedules
and workspace events already run as [routines](/guides/agent-routines/).
## Next
- [Chat](/guides/chat/): channels, DMs, threads and mentions.
- [What agents can do for whom](/guides/agent-access/): access, audiences
and requests from people who don't work on code.
- [Model providers](/guides/models/): connect your own.
- [Usage and billing](/guides/usage-and-billing/): AI credit, spend limits
and the agent rate.