Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
docs: add background agent cookbook
Autonomous agent that sweeps GitHub, Gmail, and Slack on a schedule. Uses Vercel AI SDK + OpenAI + Composio. Includes cron and GitHub Actions deployment examples. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sushmitha Mallesh committed
Mar 2, 2026 at 17:22 UTC
4f7ceb5124345c32dcd8a6efc1ddb58a0dce4d6b
4 files changed
+175
docs/content/cookbooks/background-agent.mdx
new
+129
@@ -0,0 +1,129 @@
1
+---
2
+title: Background Agent
3
+description: Build an autonomous agent that monitors GitHub, Gmail, and Slack and takes action while you sleep
4
+---
5
+
6
+[View source on GitHub](https://github.com/ComposioHQ/composio/tree/next/docs/examples/background-agent)
7
+
8
+This cookbook builds a background agent that runs a "morning sweep" across your apps. It checks GitHub for PRs that need your review, finds unanswered emails in Gmail, and posts a summary to Slack. One script, three apps, zero human input.
9
+
10
+Run it manually, put it on a cron, or deploy it. The agent does the rest.
11
+
12
+## Prerequisites
13
+
14
+* Node.js 18+
15
+* [Composio API key](https://platform.composio.dev/settings)
16
+* [OpenAI API key](https://platform.openai.com/api-keys)
17
+
18
+## Project setup
19
+
20
+Create a new project and install dependencies:
21
+
22
+```bash
23
+mkdir composio-background-agent && cd composio-background-agent
24
+npm init -y
25
+npm install ai @ai-sdk/openai @composio/core @composio/vercel dotenv tsx
26
+```
27
+
28
+Add your API keys to a `.env` file:
29
+
30
+```bash title=".env"
31
+COMPOSIO_API_KEY=your_composio_api_key
32
+OPENAI_API_KEY=your_openai_api_key
33
+```
34
+
35
+## Initializing the clients
36
+
37
+`Composio` takes a `VercelProvider` so that tools come back as Vercel AI SDK tools with built-in execution. No manual tool-call loop needed.
38
+
39
+<include meta="no-twoslash">../../examples/background-agent/sweep.ts#setup</include>
40
+
41
+## The sweep
42
+
43
+The entire agent is one function. Create a session, get tools, and give the model a prompt describing what to do. `generateText` with `stopWhen: stepCountIs(15)` lets the model call as many tools as it needs, discovering available actions, authenticating with apps, and executing across GitHub, Gmail, and Slack, all in a single run.
44
+
45
+<include meta="no-twoslash">../../examples/background-agent/sweep.ts#sweep</include>
46
+
47
+That's it. The agent figures out which tools to call, handles pagination, formats the results, and posts to Slack. Composio's meta-tools handle tool discovery and auth inline. If an app isn't connected, the agent skips it gracefully.
48
+
49
+## Complete script
50
+
51
+<include meta='no-twoslash title="sweep.ts"'>../../examples/background-agent/sweep.ts</include>
52
+
53
+## Running the sweep
54
+
55
+```bash
56
+npx tsx sweep.ts
57
+```
58
+
59
+Example output:
60
+
61
+```
62
+### GitHub: PRs where your review is requested (3)
63
+- fix: robust platform detection (ComposioHQ/composio)
64
+ https://github.com/ComposioHQ/composio/pull/2712
65
+- docs: add retry to health check workflow (ComposioHQ/composio)
66
+ https://github.com/ComposioHQ/composio/pull/2711
67
+- chore(deps): bump next (ComposioHQ/composio)
68
+ https://github.com/ComposioHQ/composio/pull/2473
69
+
70
+### Gmail: Emails from last 24h you haven't replied to (1)
71
+- Stephanie M. - CoreWeave - We'd love to chat!
72
+
73
+### Slack: Digest posted to #general
74
+```
75
+
76
+<Callout>
77
+If an app isn't connected yet, the agent will return an authentication link in the output. Open it in your browser to complete OAuth, then run the sweep again.
78
+</Callout>
79
+
80
+## Running on a schedule
81
+
82
+The agent runs once and exits, which makes it perfect for cron jobs. Pick whichever scheduler you prefer.
83
+
84
+### crontab (every day at 8am)
85
+
86
+```bash
87
+crontab -e
88
+```
89
+
90
+```
91
+0 8 * * * cd /path/to/composio-background-agent && npx tsx sweep.ts >> sweep.log 2>&1
92
+```
93
+
94
+### GitHub Actions
95
+
96
+```yaml title=".github/workflows/sweep.yml"
97
+name: Morning Sweep
98
+on:
99
+ schedule:
100
+ - cron: '0 8 * * *' # 8am UTC daily
101
+ workflow_dispatch: # manual trigger
102
+
103
+jobs:
104
+ sweep:
105
+ runs-on: ubuntu-latest
106
+ steps:
107
+ - uses: actions/checkout@v4
108
+ - uses: actions/setup-node@v4
109
+ with:
110
+ node-version: 22
111
+ - run: npm install
112
+ - run: npx tsx sweep.ts
113
+ env:
114
+ COMPOSIO_API_KEY: ${{ secrets.COMPOSIO_API_KEY }}
115
+ OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
116
+```
117
+
118
+## Take it further
119
+
120
+The prompt is the agent's brain. Change it to change what it does. Some ideas:
121
+
122
+- **Triage support tickets**: scan Zendesk for unassigned tickets, categorize them, assign to the right team in Linear
123
+- **Daily standup prep**: pull yesterday's commits from GitHub, completed tasks from Linear, and draft a standup summary
124
+- **Invoice follow-up**: check QuickBooks for overdue invoices, draft follow-up emails in Gmail
125
+
126
+<Cards>
127
+ <Card title="Hono Server" href="/cookbooks/hono" description="Wrap this agent in an HTTP server so multiple users can interact with it" />
128
+ <Card title="Vercel AI SDK Provider" href="/docs/providers/vercel" description="Learn more about how Composio tools work with the Vercel AI SDK" />
129
+</Cards>
docs/content/cookbooks/index.mdx
+1
@@ -21,6 +21,7 @@ Browse open-source templates or follow step-by-step guides below.
21
## Productivity & Automation
22
23
<Cards>
24
+ <Card title="Background Agent" href="/cookbooks/background-agent" description="Autonomous agent that monitors GitHub, Gmail, and Slack on a schedule" />
25
<Card title="Support Knowledge Agent" href="/cookbooks/support-agent" description="Agentic RAG system that searches Notion, checks Datadog, and manages GitHub issues" />
26
<Card title="Gmail Labeler" href="/cookbooks/gmail-labeler" description="Automatically label incoming emails using triggers" />
27
<Card title="Slack Summarizer" href="/cookbooks/slack-summariser" description="Summarize Slack channel messages" />
docs/content/cookbooks/meta.json
+1
@@ -9,6 +9,7 @@
9
"fast-api",
10
"hono",
11
"---Productivity & Automation---",
12
+ "background-agent",
13
"support-agent",
14
"gmail-labeler",
15
"slack-summariser",
docs/examples/background-agent/sweep.ts
new
+44
@@ -0,0 +1,44 @@
1
+import "dotenv/config";
2
+import { openai } from "@ai-sdk/openai";
3
+import { generateText, stepCountIs } from "ai";
4
+import { Composio } from "@composio/core";
5
+import { VercelProvider } from "@composio/vercel";
6
+
7
+// #region setup
8
+const composio = new Composio({ provider: new VercelProvider() });
9
+const userId = process.env.COMPOSIO_USER_ID ?? "default";
10
+const model = openai("gpt-5.2");
11
+// #endregion setup
12
+
13
+// #region sweep
14
+async function sweep() {
15
+ const session = await composio.create(userId);
16
+ const tools = await session.tools();
17
+
18
+ const { text } = await generateText({
19
+ model,
20
+ tools,
21
+ stopWhen: stepCountIs(15),
22
+ prompt: `You are an autonomous background agent running a scheduled sweep.
23
+
24
+Do the following, in order:
25
+
26
+1. **GitHub**:Find pull requests where my review is requested.
27
+ List each PR with its title, repo, and link.
28
+
29
+2. **Gmail**:Find emails from the last 24 hours that I haven't replied to.
30
+ List each with sender and subject.
31
+
32
+3. **Slack**: Post a concise summary of your findings to the #morning-sweep channel.
33
+ Format it as a digest with sections for PRs and emails.
34
+ If nothing was found, say so.
35
+
36
+If an app is not connected, skip it and note it in the summary.
37
+Be concise and actionable.`,
38
+ });
39
+
40
+ console.log(text);
41
+}
42
+
43
+sweep();
44
+// #endregion sweep