You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 046ec27
Browse filesBrowse the repository at this point in the historyBrowse files
@@ -13,141 +13,221 @@ description: Use the OpenHands Agent Canvas to gather, prioritize, and work thro
13
13
allowfullscreen
14
14
/>
15
15
16
-
Instead of manually browsing issue trackers, Slack channels, and GitHub notifications, you can have an AI agent gather, organize, and prioritize everything for you — then work through tasks one at a time without leaving the conversation.
16
+
This guide shows how to use the OpenHands Agent Canvas as a daily development work queue. The agent gathers work from GitHub and Slack, organizes it by urgency, gives you one task at a time, and can dispatch separate agents for work that can happen in parallel.
17
17
18
-
This use case walks through the workflow demonstrated in the video above, showing how to orchestrate an entire daily development routine through the OpenHands Agent Canvas.
18
+
The video above demonstrates the same workflow for readers who prefer a video walkthrough. You do not need to watch it to follow this guide.
19
19
20
-
## Overview
20
+
## What you will build
21
21
22
-
The daily workflow follows a three-phase loop:
22
+
At the end of this guide, one Agent Canvas conversation will:
23
23
24
-
1.**Gather** — The agent connects to your task management, communication, and code platforms via MCP, then collects all pending items: PRs awaiting your attention, PRs requesting review, assigned issues, Slack highlights, and GitHub notifications.
25
-
2.**Prioritize** — The agent produces a structured report organized by urgency, then gives you one task at a time so you're not overwhelmed by the full list.
26
-
3.**Execute** — You work on the task (or dispatch a subagent to handle it). When finished, you ask for the next issue. On good days, you never leave the agent interface.
24
+
1. Collect pull requests, issues, notifications, and relevant Slack activity.
25
+
2. Produce a prioritized report with links and a recommended first task.
26
+
3. Help you complete that task or start a separate agent to work on another task.
27
+
4. Continue with the next task when you are ready.
27
28
28
29
## Prerequisites
29
30
30
-
<CardGroupcols={2}>
31
-
<Cardtitle="What You Need"icon="check">
32
-
- OpenHands Agent Canvas from the [OpenHands repository](https://github.com/OpenHands/OpenHands)
33
-
- A GitHub account with access to your repositories
34
-
- A Slack workspace (or other communication tool)
35
-
- A task management tool (GitHub Issues, Linear, or Jira)
36
-
</Card>
37
-
<Cardtitle="Helpful But Optional"icon="star">
38
-
- Multiple repos under a GitHub organization for broader coverage
39
-
</Card>
40
-
</CardGroup>
31
+
41
32
42
-
## Step-by-Step Walkthrough
33
+
-[Install and start Agent Canvas](/openhands/usage/agent-canvas/setup).
34
+
- Complete [first-time setup](/openhands/usage/agent-canvas/first-time-setup), including an OpenHands agent profile, a connected backend, and an LLM.
35
+
- A GitHub account with access to the repositories you want to review.
36
+
- A Slack workspace and permission to create or install a Slack app.
43
37
44
-
### Step 1: Connect Your Tools via MCP
38
+
The workflow can use other MCP integrations, such as Linear or Jira, but the examples below use GitHub and Slack.
45
39
46
-
The agent needs access to your external tools. In the OpenHands Agent Canvas, navigate to **MCPs** to add connections:
40
+
## Step 1: Connect GitHub
47
41
48
-
**GitHub:**
49
-
1. Go to GitHub → Settings → Developer Settings → Personal Access Tokens → Fine-grained tokens
50
-
2. Generate a token scoped to your organization (e.g., `OpenHands`)
51
-
3. Select the repositories you want the agent to access
5. Paste the token into the Agent Canvas MCP configuration
42
+
The agent needs GitHub access to find assigned issues, pull requests that need your attention, review requests, notifications, and CI results.
54
43
55
-
**Slack:**
56
-
1. Get your Slack team ID from your workspace URL
57
-
2. Set up a Slack bot (e.g., via the Slack API)
58
-
3. Connect it to your workspace and select the channels to monitor
59
-
4. Grab the bot token and add it to the Agent Canvas MCP configuration
44
+
### Create a GitHub token
60
45
61
-
<Note>
62
-
You can also use other tools — Linear, Jira, GitLab, Bitbucket, or Microsoft Teams — by configuring the appropriate MCP connections. The workflow is the same regardless of which tools you use.
63
-
</Note>
46
+
1. Open [GitHub Developer Settings](https://github.com/settings/tokens).
47
+
2. Select **Fine-grained tokens** and choose **Generate new token**.
48
+
3. Give the token a name, select **Only select repositories** when possible, and set an expiration date.
49
+
4. Grant the minimum permissions for the work you want the agent to do:
64
50
65
-
### Step 2: Run the Daily Workflow
51
+
| Purpose | Permissions |
52
+
|---|---|
53
+
| Gather and report work |`Metadata: read`, `Contents: read`, `Issues: read`, `Pull requests: read`, `Actions: read`, `Checks: read`|
54
+
| Work on code or issues | Add `Contents: write` and `Issues: write`|
55
+
| Update pull requests or post reviews | Add `Pull requests: write`|
66
56
67
-
With your tools connected, trigger the workflow by telling the agent:
57
+
5. Generate the token and copy it. GitHub shows it only once.
58
+
59
+
### Add the GitHub MCP server
60
+
61
+
Use the backend where this conversation will run. The MCP server and its saved secret belong to that backend.
62
+
63
+
1. In Agent Canvas, confirm the correct backend in the backend switcher.
64
+
2. Open **Customize** in the left navigation.
65
+
3. Open **MCP Servers**.
66
+
4. Select **GitHub** from the MCP library.
67
+
5. Paste the token into the token field.
68
+
6. Leave the option to create a secret enabled, then save the server.
69
+
7. Wait for the server card to report a healthy connection.
70
+
71
+
See [MCP server settings](/openhands/usage/settings/mcp-settings) for general configuration and troubleshooting details. Do not paste tokens into the conversation itself.
72
+
73
+
## Step 2: Connect Slack
74
+
75
+
Slack access lets the agent find mentions, threads, and messages that need your response. The bot can read only channels it can access.
76
+
77
+
### Create and install a Slack app
78
+
79
+
1. Open the [Slack API dashboard](https://api.slack.com/apps) and select **Create New App** → **From scratch**.
80
+
2. Choose the workspace where the app will read messages.
81
+
3. In **OAuth & Permissions**, add these bot scopes:
|`groups:history`| Read private-channel messages where the bot is a member |
88
+
|`users:read`| Resolve people mentioned in messages |
89
+
|`chat:write`| Allow the agent to post replies when you explicitly ask it to |
90
+
91
+
4. Select **Install to Workspace**, approve the permissions, and copy the **Bot User OAuth Token**.
92
+
5. Invite the bot to each channel it should monitor. The bot cannot read channels it has not joined.
93
+
6. Find your workspace ID from your Slack workspace URL or [Slack's workspace-ID guide](https://slack.com/help/articles/221769328-Locate-your-Slack-URL-or-ID).
94
+
95
+
### Add the Slack MCP server
96
+
97
+
The same **Customize → MCP Servers** screen is used for Slack.
98
+
99
+
1. In Agent Canvas, open **Customize** → **MCP Servers**.
100
+
2. Select **Slack** from the MCP library.
101
+
3. Paste the bot token and enter the workspace ID.
102
+
4. Keep secret creation enabled and save the server.
103
+
5. Wait for a healthy connection, then verify that the bot can access the channels you want to search.
Create a new conversation in Agent Canvas and send this prompt:
68
110
69
111
```
70
-
Do my daily workflow.
112
+
Do my daily workflow using the connected GitHub and Slack MCP servers.
113
+
114
+
Gather:
115
+
- pull requests that need my attention or review
116
+
- assigned issues
117
+
- GitHub notifications and failing CI
118
+
- Slack mentions, threads, and messages that need a response
119
+
120
+
Group the results by urgency. For every item, include its title, why it matters,
121
+
and a direct link. End with the single highest-priority task for me to start.
122
+
Do not make changes or send messages without asking me first.
123
+
```
124
+
125
+
If you use Linear, Jira, or another connected service, add it explicitly to the prompt. For example:
126
+
127
+
```
128
+
Also check my assigned Linear issues and current cycle.
71
129
```
72
130
73
-
Tell the agent what to do: gather tasks from all connected sources, organize them, and produce a structured report.
131
+
The agent may ask clarifying questions, such as which repositories or Slack channels to include. Answer those questions before asking it to produce the final report.
74
132
75
-
You can also customize the instructions. For example, to limit scope or change the output format:
133
+
## Step 4: Read the prioritized report
134
+
135
+
Ask for a report in this format if the first response is not organized clearly:
76
136
77
137
```
78
-
Do my daily workflow, but only use your MCP tools for GitHub and Slack.
79
-
At the end, give me a structured report of all of the things to do today,
80
-
and then give me my first task to do.
138
+
Organize the results into:
139
+
1. Immediate action
140
+
2. PRs waiting for my response
141
+
3. PRs requesting my review
142
+
4. Assigned issues
143
+
5. Slack highlights
144
+
6. GitHub notifications
145
+
146
+
Sort each section by urgency. Include direct links and finish by recommending one first task.
81
147
```
82
148
83
-
The key insight: **skills provide a reusable base that you can diverge from**. You don't need to re-explain the entire workflow each time — just specify what's different.
149
+
A useful report looks like this:
150
+
151
+
```text
152
+
## Immediate action
153
+
- Fix failing CI on PR #123 — blocking the release — <link>
84
154
85
-
### Step 3: Review the Structured Report
155
+
## PRs waiting for my response
156
+
- Address requested changes on PR #456 — <link>
86
157
87
-
After a few minutes, the agent returns a structured report. A typical report includes:
|**Immediate Action**| CI is stuck on a PR — needs a fix to unblock the team |
92
-
|**PRs Awaiting Your Attention**| Changes requested on a 623-line PR that a team is waiting on |
93
-
|**PRs Requesting Your Review**| Two PRs from teammates needing review |
94
-
|**Assigned Issues**| Three GitHub issues assigned to you |
95
-
|**Slack Highlights**| Important mentions or threads requiring a response |
96
-
|**GitHub Notifications**| Workflow failures, mentions, or assignment notifications |
161
+
## Assigned issues
162
+
- Document the new API behavior — <link>
97
163
98
-
The agent then gives you **one task at a time** — the highest-priority item — so you can focus without being overwhelmed by the full list.
164
+
## Slack highlights
165
+
- Reply to the deployment question in #engineering — <link>
99
166
100
-
### Step 4: Work Through Tasks
167
+
## GitHub notifications
168
+
- Workflow failure on repository-name — <link>
101
169
102
-
For each task the agent presents:
170
+
## First task
171
+
Fix the failing CI on PR #123.
172
+
```
173
+
174
+
The report is a starting point, not a guarantee that every source contains actionable work. Ask the agent to search a specific repository, channel, or date range when an important item is missing.
103
175
104
-
1.**Ask for links** — Say "give me links to those" and the agent provides clickable URLs to the PR, issue, or Slack thread
105
-
2.**Start working** — Click through and begin the task, or ask the agent to handle it directly
106
-
3.**Dispatch subagents** — For parallelizable work, start a background agent to remediate failing CI or address review comments on your other open PRs
107
-
4.**Move to the next task** — When finished, say "I finished those. Give me the next issue to work on."
176
+
## Step 5: Work through one task at a time
108
177
109
-
The agent can also **dispatch subagents** via the Agent Canvas to work on remediation in parallel:
178
+
When the agent recommends a task:
179
+
180
+
1. Ask for links if the report does not include them: `Give me the links for that task.`
181
+
2. Tell the agent whether you want investigation, implementation, or only a summary.
182
+
3. Set the safety boundary before it changes anything. For example:
110
183
111
184
```
112
-
Dispatch another agent to remediate all failing CI and
113
-
unaddressed review comments on my open PRs.
185
+
Inspect the failing CI on PR #123, explain the root cause, and propose a fix.
186
+
Do not edit files, push changes, or comment on GitHub until I approve the plan.
114
187
```
115
188
116
-
This lets you focus on high-priority work while the subagent handles routine fixes in the background.
117
-
118
-
## Key Technical Details
189
+
4. After reviewing the result, ask it to implement the approved change, run the relevant checks, and report what changed.
190
+
5. When the task is complete, ask:
119
191
120
-
### MCP Tool Permissions
192
+
```
193
+
I finished that task. Re-check the remaining work and give me the next highest-priority item.
194
+
```
121
195
122
-
The agent's effectiveness depends on having the right MCP permissions configured:
196
+
The agent can inspect and edit files in its configured workspace, but its ability to push code, update GitHub, or post to Slack depends on the permissions granted to the MCP servers and the confirmation policy you use.
|**Linear** (optional) |`read` access to issues, assignments, and cycle information |
198
+
## Step 6: Dispatch parallel work
129
199
130
-
### Skills as Reusable Workflows
200
+
Use a separate agent only for work that is independent of the task you are handling. For example:
131
201
132
-
The workflow is straightforward to repeat in the Agent Canvas. The agent can:
202
+
```
203
+
Start a separate agent to inspect the failing CI and unaddressed review comments
204
+
on my other open pull requests. It may modify files in its own workspace and
205
+
run tests, but it must not push, merge, or post comments. Return a summary and
206
+
proposed changes when finished.
207
+
```
133
208
134
-
- Query all connected MCP tools for pending items
135
-
- Categorize and prioritize results
136
-
- Format a structured report
137
-
- Present tasks one at a time
209
+
Before dispatching, specify:
138
210
211
+
- Which repositories, pull requests, or issues it may access
212
+
- Whether it may edit files
213
+
- Which tests it should run
214
+
- Whether it may push branches or post comments
215
+
- What it should return when finished
139
216
140
-
### Subagent Dispatch
217
+
Keep related changes in separate workspaces or branches to avoid overwriting your active work. Review a subagent's summary and diff before asking it to push or make external changes. You can continue the original conversation while the separate agent runs, then inspect its conversation from the Agent Canvas conversation list.
141
218
142
-
The Agent Canvas supports dispatching subagents — separate agent conversations that run in the background. This is useful for:
219
+
## Troubleshooting
143
220
144
-
-**CI remediation** — Fix failing builds on PRs you're not actively working on
-**Parallel task execution** — Work on multiple issues simultaneously
221
+
-**The agent cannot find GitHub work:** confirm the GitHub MCP server is healthy, the token includes the required repositories, and the token has not expired.
222
+
-**Slack results are empty:** confirm the bot is installed in the workspace and invited to each channel you want to search.
223
+
-**The agent reports no tools:** start a new conversation after adding or changing an MCP server; MCP configuration is loaded when a conversation starts.
224
+
-**The report is too broad:** name the repositories, Slack channels, date range, or task categories to include.
225
+
-**The agent tries to act too early:** state that it must ask for approval before editing files, pushing, or posting messages.
147
226
148
-
## Related Resources
227
+
## Reference
149
228
150
-
-[Daily Workflow Video](https://youtu.be/S_wap45Iq8U) — Full walkthrough of the daily development workflow
151
-
-[MCP Overview](/overview/model-context-protocol) — How to connect external tools
0 commit comments