| 1 | --- |
| 2 | title: Agent abilities |
| 3 | description: What an agent may do, in groups - g1t's own, its computer, each connected integration, and the connectors and MCP servers it has - and for each whether it acts alone, only when asked for it, after asking first, or never; whose connection it uses; and the cards it posts when it can't. |
| 4 | --- |
| 5 | |
| 6 | Every agent has an **Abilities** tab on its page, after **Skills**. It |
| 7 | lists what the agent can do, in groups, and for each ability a **level** |
| 8 | that says how freely it may do it. The levels are enforced in code: a |
| 9 | tool the agent isn't allowed is withheld, and one it may use only after |
| 10 | asking posts a card and waits. The tab opens with the whole thing in a |
| 11 | sentence, such as *Can read issues in Linear and open pull requests on its |
| 12 | own; imports issues in Linear when asked for it; asks before commenting in |
| 13 | Linear and merging; never deploys to production.* |
| 14 | |
| 15 | Skills tell an agent how to do a kind of work; abilities say what it may |
| 16 | touch. A skill never adds an ability (see |
| 17 | [agent skills](/guides/agent-skills/)), and an agent never does more for |
| 18 | someone than that person could do themselves (see |
| 19 | [what agents can do for whom](/guides/agent-access/)). |
| 20 | |
| 21 | ## The levels |
| 22 | |
| 23 | | Level | What it means | |
| 24 | | --- | --- | |
| 25 | | **Alone** | It does it when its work calls for it, and says so. | |
| 26 | | **Alone when asked for it** | It does it on its own when the person it acts for named the thing in what they asked (the issue's key, or the action), and asks first otherwise. | |
| 27 | | **Ask first** | It posts a card in the conversation saying exactly what it would do. The person it acts for, or an owner, presses **Allow** or **Deny**. Allowed, it runs as the person who pressed, and the agent hears the result. | |
| 28 | | **Never** | The tool isn't offered. If the agent asks for it anyway, it is refused with the rule's name, and says so plainly rather than trying another way. | |
| 29 | |
| 30 | Defaults follow what an ability does: |
| 31 | |
| 32 | | What it does | Default | Freest it can be set | |
| 33 | | --- | --- | --- | |
| 34 | | Reads | Alone | Alone | |
| 35 | | Writes inside g1t (opens an issue, a pull request, an edit) | Alone when asked for it, or today's choice for code and docs | Alone | |
| 36 | | Sends something outside g1t (a comment in another system, a message, a change there) | Ask first | Alone | |
| 37 | | Purchases, credentials and permission changes (a production deploy) | Never | Ask first | |
| 38 | |
| 39 | Every change to a level is saved as a new version of the agent, like any |
| 40 | other change on its profile, and shows under **Profile → Versions** as a |
| 41 | change to its abilities. |
| 42 | |
| 43 | ## The groups |
| 44 | |
| 45 | ### g1t |
| 46 | |
| 47 | Artifacts, chat, code, issues and pull requests, making files, and working |
| 48 | with colleagues and memory are always on, within the access of the person |
| 49 | the agent acts for and everyone who will read its answer. They have no |
| 50 | level to set. Four of them keep a choice, the same choice as |
| 51 | [what it may do alone](/guides/agents/#what-it-may-do-alone) on the Profile |
| 52 | tab: |
| 53 | |
| 54 | | Ability | Choices | Default | |
| 55 | | --- | --- | --- | |
| 56 | | Open pull requests | Alone, Ask first | Alone | |
| 57 | | Merge | Alone, Ask first, Never | Ask first | |
| 58 | | Deploy to production | Ask first, Never | Ask first | |
| 59 | | Edit docs | Alone, Ask first (as suggestions) | Ask first | |
| 60 | |
| 61 | Changing one here changes it there, and the other way round. |
| 62 | |
| 63 | ### Its computer |
| 64 | |
| 65 | What the agent may do on [its own computer](/guides/agents/#its-computer), |
| 66 | in its sessions. Chat replies never use the computer, whatever is set here. |
| 67 | |
| 68 | | Ability | Tools it offers | Kind | Default | |
| 69 | | --- | --- | --- | --- | |
| 70 | | Shell | `run_command` | Write | Alone when asked for it | |
| 71 | | Files | `computer_read_file` · `computer_write_file` | Write | Alone | |
| 72 | | Browser | — | Send | Coming | |
| 73 | | Web search | — | Read | Coming | |
| 74 | |
| 75 | Set to **Never**, an ability's tools are not offered to the agent at all, |
| 76 | and a call for one anyway is refused with the rule. For the shell at |
| 77 | **Alone when asked for it**, the session's goal or a message steering it |
| 78 | counts as asking when it names running, building, testing, installing, |
| 79 | cloning or the like; otherwise the command waits on an Ask-first card, with |
| 80 | the command on it. Files are alone by default, since nothing leaves the |
| 81 | computer. A browser and web search are marked **Coming** until they exist; |
| 82 | nothing can be set for them yet. |
| 83 | |
| 84 | ### Integrations |
| 85 | |
| 86 | Every integration the workspace has connected lists what an agent can do |
| 87 | through it, one row per action, with a level for each. What is listed |
| 88 | comes from what the integration does today: |
| 89 | |
| 90 | | Integration | Rows | Tool the agent calls | |
| 91 | | --- | --- | --- | |
| 92 | | Linear | Read issues · Import issues · Comment | `lookup_outside` · `import_outside` · `act_outside` | |
| 93 | | Jira | Read tickets · Import tickets · Comment | `lookup_outside` · `import_outside` · `act_outside` | |
| 94 | | Sentry | Read issues · Import issues · Comment · Resolve issues | `lookup_outside` · `import_outside` · `act_outside` | |
| 95 | | Datadog, Alerts webhook | None: they open issues by themselves | — | |
| 96 | |
| 97 | Reading looks an item up by its key (`ENG-42`, `TECH-1234`) or its |
| 98 | address. Importing opens an issue in a repository here, linked back to |
| 99 | the item, as the person the agent acts for. Commenting and resolving write |
| 100 | in the other system, as the workspace's connection, and name the person |
| 101 | the agent acted for with a link back to the conversation. |
| 102 | |
| 103 | An integration that gives agents abilities but isn't connected is listed |
| 104 | too, with **Connect** for owners and **Ask an owner** for anyone else, |
| 105 | which opens it in [Customize](/guides/customize/#connectors). Nothing on |
| 106 | it can be set until it is connected. |
| 107 | |
| 108 | #### Whose connection |
| 109 | |
| 110 | Each integration row says whose connection it runs on: |
| 111 | |
| 112 | | | | |
| 113 | | --- | --- | |
| 114 | | **Workspace connection** | The agent acts as the integration's connection for the whole workspace, the one an owner set up under Integrations. Only owners choose this. | |
| 115 | | **Asker's connection** | The agent acts as the asking person's own account. When they haven't connected one, the agent posts a **Connect** card in the conversation: one press opens their own settings for it. | |
| 116 | |
| 117 | A [personal agent](/guides/agents/#personal-agents) starts on the asker's |
| 118 | connection; an owner can put it on the workspace's. Linear, Jira and |
| 119 | Sentry can't be connected per person yet, so for them the choice is the |
| 120 | workspace's connection today. |
| 121 | |
| 122 | ### Connectors |
| 123 | |
| 124 | MCP servers reach an agent in two ways, and the tab lists both under |
| 125 | **Connectors**: |
| 126 | |
| 127 | - **The workspace's connectors**, connected once in |
| 128 | [Customize](/guides/customize/#connectors) and given to every agent, a |
| 129 | team or this agent. Each row says how the agent has it (**Every agent**, |
| 130 | **Team QA**, **This agent**) and its state. A connector that needs a |
| 131 | sign-in or a key, or has a problem, gives the agent nothing until an |
| 132 | owner fixes it there. Servers that need a key or a browser sign-in are |
| 133 | connected this way. |
| 134 | - **Only this agent**: servers owners add to this agent alone, one at a |
| 135 | time, by a name and an HTTPS address on a public host, with no sign-in. |
| 136 | An agent keeps at most 10. |
| 137 | |
| 138 | g1t lists a server's tools when it is connected or added, keeps the first |
| 139 | 40, and each tool becomes a row: |
| 140 | |
| 141 | - a tool the server marks as read-only is a **read**, Alone by default; |
| 142 | - any other tool, including one the server says nothing about, counts as |
| 143 | a **write outside g1t**, Ask first by default. |
| 144 | |
| 145 | Tools are offered to the agent as `<server>__<tool>`, with the arguments |
| 146 | the server describes. For a server added to this agent alone, **List its |
| 147 | tools again** picks up a server that changed and **Remove** takes the |
| 148 | server and its rows off the agent at once; both are new versions of the |
| 149 | agent. A workspace connector is listed again, signed in, given and taken |
| 150 | back on its own page in Customize, and the tab links there. |
| 151 | |
| 152 | ## Ask first, in the conversation |
| 153 | |
| 154 | When an ability is Ask first (or Alone when asked for it, and the person |
| 155 | didn't ask), the agent posts a card where it is working: what it would |
| 156 | do, for whom, and under which rule, with the text it would write. The |
| 157 | person it acts for, or an owner, presses **Allow** or **Deny**: |
| 158 | |
| 159 | - **Allow** runs the call as the person who pressed it. The card then says |
| 160 | what happened, and the agent is told the result. A session that was |
| 161 | waiting goes on with it at its next step. |
| 162 | - **Deny** tells the agent, which says so and doesn't try another way. |
| 163 | |
| 164 | A [session](/guides/agent-sessions/) with a call waiting shows **Needs |
| 165 | approval** and the call it waits for, until the card is answered or the |
| 166 | session is stopped. |
| 167 | |
| 168 | ## When something is missing |
| 169 | |
| 170 | When a request needs an integration that isn't connected, or an ability |
| 171 | the agent doesn't have, the agent says so plainly and posts a **Request** |
| 172 | card: |
| 173 | |
| 174 | - for an integration or a connector, **Ask the owners** opens the same |
| 175 | request Customize does (see [requests](/guides/customize/#requests)), |
| 176 | and **Open in Customize** goes to its page; |
| 177 | - for an ability, **Ask the owners** notifies every owner with a link to |
| 178 | the agent's Abilities tab, and **Open Abilities** goes there. |
| 179 | |
| 180 | Owners see a link to do it themselves instead. |
| 181 | |
| 182 | ## Refusals, in the transcript and the audit log |
| 183 | |
| 184 | A policy fails closed. When a tool is withheld or a call is refused, the |
| 185 | agent's answer says which rule refused it, such as *Linear: Comment is |
| 186 | Never*, and so does the session's transcript (the tool call shows as |
| 187 | refused). The workspace's [audit log](/guides/audit-log/) records every |
| 188 | refusal under the agent, with the rule (`integration:linear:comment=never`) |
| 189 | and what was refused, and every Allow or Deny under the person who |
| 190 | pressed it. |
| 191 | |
| 192 | ## Who edits |
| 193 | |
| 194 | | Agent | Who changes its abilities | |
| 195 | | --- | --- | |
| 196 | | A workspace agent | The workspace's owners. | |
| 197 | | A personal agent | The member it belongs to, except that only owners put it on the workspace's connection. | |
| 198 | | `@g1t` | Owners, like any workspace agent. | |
| 199 | |
| 200 | Everyone in the workspace can read the tab. |
| 201 | |
| 202 | ## API |
| 203 | |
| 204 | An agent's abilities are part of its definition: `abilities.settings`, |
| 205 | by ability id (`integration:linear:comment`), each with a `level` |
| 206 | (`alone`, `asked`, `ask`, `never`) and, for an integration, `credentials` |
| 207 | (`workspace` or `asker`); and `abilities.mcp_servers`. Changing an agent |
| 208 | with `abilities: { settings }` replaces its settings, and is a new |
| 209 | version like any change. MCP servers are added and removed with the |
| 210 | agents service's `add_mcp_server`, `refresh_mcp_server` and |
| 211 | `remove_mcp_server`; they never travel with a change. The workspace's |
| 212 | connectors and who gets them are the [`customize`](/guides/customize/#api) |
| 213 | resource's; which ones reach an agent is read with the agents service's |
| 214 | `agent_connectors`. |
| 215 | |
| 216 | The computer itself has routes of its own under the agent: |
| 217 | `GET /workspaces/{workspace}/agents/{agent}/computer` for its state and |
| 218 | recent commands, `POST …/computer/wake`, `…/computer/sleep` and |
| 219 | `…/computer/reset`, and `GET …/computer/commands`; in MCP, the `agent` |
| 220 | tool's `computer`, `wake_computer`, `sleep_computer`, `reset_computer` and |
| 221 | `computer_commands` actions, all under `agents:run`. |
| 222 | |
| 223 | ## Next |
| 224 | |
| 225 | - [Agents](/guides/agents/): hiring, changing and running agents. |
| 226 | - [Agent skills](/guides/agent-skills/): how an agent does a kind of work. |
| 227 | - [Customize](/guides/customize/): connecting connectors and integrations, and asking an owner to. |
| 228 | - [What agents can do for whom](/guides/agent-access/): the access every ability runs within. |