@devries-cameron20 / composio Mirror · read-only / commits / 4f7ceb512
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 05:45 UTC

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