Developing agents (Beta)

This guide describes how to best integrate an AI agent into Linear. It includes implementation guidelines on how to design an experience that feels native to Linear’s workflows and interaction patterns.

Agents, also known as "app users", behave similar to other users in a workspace. They can be @-mentioned, assigned issues, create and reply to comments, collaborate on projects and documents, etc. App users are installed and managed by workspace admins.

You can build agents for internal use within your own workspace or for distribution to other organizations. It does not cost anything to develop or use agents in Linear. To make your agent available to other organizations, submit your agent to Linear's integration directory.

Setup⁠

Create a new Application and configure the settings as you would for a standard OAuth application.

In the configuration, enable webhooks and make sure to select Inbox notifications at the bottom. Enabling this category will notify your webhook when events occur that are directly relevant to your app's user.

Authentication⁠

Actor and scopes⁠

App authentication is built on top of the standard OAuth2 flow. To install your agent into a Linear workspace in the OAuth authorization url add the actor=app parameter to switch to an app installation rather than requesting authentication as the installing user. Because this will be installed with a workspace scope admin permissions are required to complete the installation.

This new actor type supersedes any references to actor=application and can be used for all agent, app, and service account use-cases.

Mention + assign scopes⁠

To allow for flexibility, the ability to mention and assign your agent is optional and must be requested through the use of two new additional scopes added to the scope query parameter:

Admin⁠

Note that integrations using the actor=app mode are not able to also request admin scope.

Installation⁠

Your app will have a unique ID for each workspace it is installed within, you can find this ID with the following query using the OAuth access token received as part of the installation flow:

query Me {
  viewer {
    id
  }
}

We highly recommend storing this ID alongside your access token so that you can confidently identify your app in different workspaces.

Management⁠

The team access available to your app can be changed or revoked at any time by workspace admins. Please account for this possibly changing – we will have new webhook events to subscribe to for these events soon.

Handling interaction⁠

Linear users have high expectations for the quality and consistency of the experience inside Linear. We aim to extend this to agents, which should act in a predictable and natural manner.

Recommendations⁠

1. Immediately acknowledge when your agent has been interacted with within Linear. We will introduce some additional primitives in the future, and for now we recommend responding with a reaction or a comment to make it clear that instruction was received.
2. If your agent is assigned an issue that is not in a started, completed, or canceled status type, move the issue to the first status in started when your agent begins work.
3. Respond when work is complete. We recommend leaving a comment or reply to let the original user know, which will trigger a notification to their Linear inbox.

Webhooks⁠

In order to support these recommended flows, we have introduced a new webhook type Inbox notifications. Ensure that these are enabled in your OAuth application config. These events will be triggered when events occur that are directly relevant to your app user.

The received webhook payload will have the following shape:

{
  type: "AppUserNotification",
  action: NotificationType,
  createdAt: string,
  organizationId: string,
  oauthClientId: string,
  appUserId: string,
  notification: Notification,
}

The following action type's are particularly interesting as part of implementing the above recommendations:

issueMention
issueEmojiReaction
issueCommentMention
issueCommentReaction
issueAssignedToYou
issueUnassignedFromYou
issueNewComment
issueStatusChanged

Existing integrations⁠

Recommendations on when to build an integration or agent⁠

Build a standard integration when you want to authorize each individual user to attribute actions to a user rather than the app in general. If your integration primarily reads data from Linear or performs actions that should be attributed to individual team members, an integration is the right choice.

The app actor is better suited when your tool needs to appear as a distinct workspace member with its own identity and actions within Linear. This includes automation tools, CI/CD pipelines, and external services. Agents provide clear tracking of which system made changes and offer better permissions management for these operations.

Convert an existing integration⁠

If you have an existing Linear integration it can be converted to use the new authentication and gain the new functionality.

The new actor=app actor type works quite differently at the core to our legacy actor=application approach. However, if you are using actor=application today to request a token that is only used to create issues or comments as an app, then it is backwards compatible – you can simply change this parameter.

actor=application allows for dual-purpose authentication tokens that can be used both as the authenticating user in some circumstances and as an "app" in others. If you currently are using a token like this, then to migrate you will need to ask users to authenticate twice: once for their personal access and secondarily for the app installation.

Feedback, requests, questions⁠

Please join the #api-agents channel in our community Slack to provide feedback on this guide, request API's, and interact with other engineers developing agentic integrations.