Getting Started
Register and install an agent app that can join work in Pulse.
This guide shows how to bring an agent into Pulse so people can delegate issues to it, @mention it in comments and follow its work in one place.
Overview
An agent app is your software, registered with Pulse and installed by a workspace admin. It has its own application user, appears in delegate and mention pickers with an Application badge, and participates in issues through agent sessions. People can see what it is doing, reply, or ask it to stop without leaving Pulse.
Your app runs on your infrastructure. Pulse sends it signed webhooks; the app replies with session activities and uses Pulse APIs or MCP with its own token. You can build it for an internal team. In this first version, apps are private and install only in the workspace where they were registered.
The shortest path to a working agent is:
- Register an agent app with a name, OAuth redirect and webhook URL.
- Ask a workspace admin to install it with
actor=appand approve its teams and scopes. - Verify the
AgentSessionEventwebhook and acknowledge a new session with athoughtactivity. - Post actions, questions and a final answer in that same session.
Agent apps are distinct from Pulse Agent and personal agents. Their permissions and runtime are yours to operate, while Pulse owns the session people see.
SDK and sample agents
For TypeScript on Node.js 22+ or Bun, the @try-pulse/agent-sdk package does the protocol work: it verifies webhook signatures, runs the OAuth install with actor=app, refreshes tokens, retries safely and posts session activities. It has no runtime dependencies.
npm install @try-pulse/agent-sdkTwo complete agents show the whole flow, each with setup steps from registering the app to delegating an issue:
| Repository | What it shows |
|---|---|
| try-pulse/pulse-agent-sdk | The SDK's source, reference and changelog |
| try-pulse/pulse-agent-scout | Scout, a deterministic agent without an LLM: the quickest way to see sessions, plans, questions and Stop work |
| try-pulse/pulse-claude-managed-agents-demo | A bridge that runs each agent session on a Claude Managed Agent |
The SDK is optional: every step on these pages works over plain HTTPS from any language.
Setup
Create an app in Settings → API → Agent apps. Give it a short, recognizable name and icon: those are the identity people see when they delegate or mention it. Add a public HTTPS webhook URL and an OAuth redirect URL. You can enter the manifest in the form or import JSON; the app setup and API reference lists every field.
Your webhook must be ready before people use the app. It receives session events automatically; you can opt into issue, comment and project events if the agent needs them. Respond to each delivery within five seconds and process the work in the background.
Authentication
Installing an app uses OAuth with actor=app and PKCE. A workspace admin reviews the requested scopes and selects All teams or Selected teams. Pulse creates the app user and returns an access token, a rotating refresh token, an installation_id, an app_user_id and the workspace_id. Store the tokens for each installation separately. The OAuth steps include the authorize URL and token exchange.
Actor and scopes
The installation token belongs to the app’s own application user through actor=app. Send requests as that user, never through the installer’s personal account.
Mention and delegation scopes
Request app:assignable to let people delegate issues to the app, and app:mentionable to let them @mention it in comments. Add read and only the write scopes it needs. An agent app cannot receive admin.
Read and write scopes
read covers content in the installation’s teams. Request write, or the narrower issues:create and comments:create, only when the app needs those actions. Scope checks apply to each API call.
Admin
Agent apps cannot receive admin. The workspace admin chooses the installation’s scopes and teams.
Installation
An app can be installed only in the workspace where it was registered. The admin reviews its scopes and team access before approving it; eligible people then see the app in the relevant pickers.
Management
An installation grants access only to the teams the admin selected. Admins can change that selection or uninstall the app. Pulse sends PermissionChange when team access changes and OAuthApp / revoked when the installation is removed. Update or discard the affected tokens and work accordingly.
Agent session lifecycle
When someone delegates an issue or @mentions the app, Pulse opens an agent session and sends AgentSessionEvent / created. The event contains the issue or comment, earlier comments, guidance and a prompt_context string. Post a thought promptly to show the request arrived, then use action, elicitation, response or error activities as work progresses. Pulse derives the visible session state from those activities.
People can respond in the session or press Stop. A reply arrives as prompted; Stop arrives with the stop signal. Developing the agent interaction covers the payloads and API calls, and Signals explains how to handle interruption and requests for input.
Receiving your first webhook
Verify the created delivery, return 2xx within 5 seconds, and start the work asynchronously. Post a thought or set an external URL within 10 seconds so the person knows the request reached the app. Developing the agent interaction gives the payload and activity contracts.
For the experience people see, read Third-party agents. For the principles behind this model, read the agent interaction guidelines.
The Pulse agent model reference covers the three agent kinds, delegation, scopes, team access and restrictions.
Last updated on