Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: add background agent cookbook
Sushmitha Mallesh4f7ceb512434
diff --git a/docs/content/cookbooks/background-agent.mdx b/docs/content/cookbooks/background-agent.mdxnew file mode 100644index 000000000..cd5cb0466--- /dev/null+++ b/docs/content/cookbooks/background-agent.mdx@@ -0,0 +1,129 @@+---+title: Background Agent+description: Build an autonomous agent that monitors GitHub, Gmail, and Slack and takes action while you sleep+---++[View source on GitHub](https://github.com/ComposioHQ/composio/tree/next/docs/examples/background-agent)++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.++Run it manually, put it on a cron, or deploy it. The agent does the rest.++## Prerequisites++* Node.js 18++* [Composio API key](https://platform.composio.dev/settings)+* [OpenAI API key](https://platform.openai.com/api-keys)++## Project setup++Create a new project and install dependencies:++```bash+mkdir composio-background-agent && cd composio-background-agent+npm init -y+npm install ai @ai-sdk/openai @composio/core @composio/vercel dotenv tsx+```++Add your API keys to a `.env` file:++```bash title=".env"+COMPOSIO_API_KEY=your_composio_api_key+OPENAI_API_KEY=your_openai_api_key+```++## Initializing the clients++`Composio` takes a `VercelProvider` so that tools come back as Vercel AI SDK tools with built-in execution. No manual tool-call loop needed.++<include meta="no-twoslash">../../examples/background-agent/sweep.ts#setup</include>++## The sweep++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.++<include meta="no-twoslash">../../examples/background-agent/sweep.ts#sweep</include>++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.++## Complete script++<include meta='no-twoslash title="sweep.ts"'>../../examples/background-agent/sweep.ts</include>++## Running the sweep++```bash+npx tsx sweep.ts+```++Example output:++```+### GitHub: PRs where your review is requested (3)+- fix: robust platform detection (ComposioHQ/composio)+ https://github.com/ComposioHQ/composio/pull/2712+- docs: add retry to health check workflow (ComposioHQ/composio)+ https://github.com/ComposioHQ/composio/pull/2711+- chore(deps): bump next (ComposioHQ/composio)+ https://github.com/ComposioHQ/composio/pull/2473++### Gmail: Emails from last 24h you haven't replied to (1)+- Stephanie M. - CoreWeave - We'd love to chat!++### Slack: Digest posted to #general+```++<Callout>+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.+</Callout>++## Running on a schedule++The agent runs once and exits, which makes it perfect for cron jobs. Pick whichever scheduler you prefer.++### crontab (every day at 8am)++```bash+crontab -e+```++```+0 8 * * * cd /path/to/composio-background-agent && npx tsx sweep.ts >> sweep.log 2>&1+```++### GitHub Actions++```yaml title=".github/workflows/sweep.yml"+name: Morning Sweep+on:+ schedule:+ - cron: '0 8 * * *' # 8am UTC daily+ workflow_dispatch: # manual trigger++jobs:+ sweep:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4+ - uses: actions/setup-node@v4+ with:+ node-version: 22+ - run: npm install+ - run: npx tsx sweep.ts+ env:+ COMPOSIO_API_KEY: ${{ secrets.COMPOSIO_API_KEY }}+ OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}+```++## Take it further++The prompt is the agent's brain. Change it to change what it does. Some ideas:++- **Triage support tickets**: scan Zendesk for unassigned tickets, categorize them, assign to the right team in Linear+- **Daily standup prep**: pull yesterday's commits from GitHub, completed tasks from Linear, and draft a standup summary+- **Invoice follow-up**: check QuickBooks for overdue invoices, draft follow-up emails in Gmail++<Cards>+ <Card title="Hono Server" href="/cookbooks/hono" description="Wrap this agent in an HTTP server so multiple users can interact with it" />+ <Card title="Vercel AI SDK Provider" href="/docs/providers/vercel" description="Learn more about how Composio tools work with the Vercel AI SDK" />+</Cards>diff --git a/docs/content/cookbooks/index.mdx b/docs/content/cookbooks/index.mdxindex adb0e6f4b..11d8ac81f 100644--- a/docs/content/cookbooks/index.mdx+++ b/docs/content/cookbooks/index.mdx@@ -21,6 +21,7 @@ Browse open-source templates or follow step-by-step guides below.## Productivity & Automation<Cards>+ <Card title="Background Agent" href="/cookbooks/background-agent" description="Autonomous agent that monitors GitHub, Gmail, and Slack on a schedule" /><Card title="Support Knowledge Agent" href="/cookbooks/support-agent" description="Agentic RAG system that searches Notion, checks Datadog, and manages GitHub issues" /><Card title="Gmail Labeler" href="/cookbooks/gmail-labeler" description="Automatically label incoming emails using triggers" /><Card title="Slack Summarizer" href="/cookbooks/slack-summariser" description="Summarize Slack channel messages" />diff --git a/docs/content/cookbooks/meta.json b/docs/content/cookbooks/meta.jsonindex 2bf335eb5..d781c9d28 100644--- a/docs/content/cookbooks/meta.json+++ b/docs/content/cookbooks/meta.json@@ -9,6 +9,7 @@"fast-api","hono","---Productivity & Automation---",+ "background-agent","support-agent","gmail-labeler","slack-summariser",diff --git a/docs/examples/background-agent/sweep.ts b/docs/examples/background-agent/sweep.tsnew file mode 100644index 000000000..9b975430f--- /dev/null+++ b/docs/examples/background-agent/sweep.ts@@ -0,0 +1,44 @@+import "dotenv/config";+import { openai } from "@ai-sdk/openai";+import { generateText, stepCountIs } from "ai";+import { Composio } from "@composio/core";+import { VercelProvider } from "@composio/vercel";++// #region setup+const composio = new Composio({ provider: new VercelProvider() });+const userId = process.env.COMPOSIO_USER_ID ?? "default";+const model = openai("gpt-5.2");+// #endregion setup++// #region sweep+async function sweep() {+ const session = await composio.create(userId);+ const tools = await session.tools();++ const { text } = await generateText({+ model,+ tools,+ stopWhen: stepCountIs(15),+ prompt: `You are an autonomous background agent running a scheduled sweep.++Do the following, in order:++1. **GitHub**:Find pull requests where my review is requested.+ List each PR with its title, repo, and link.++2. **Gmail**:Find emails from the last 24 hours that I haven't replied to.+ List each with sender and subject.++3. **Slack**: Post a concise summary of your findings to the #morning-sweep channel.+ Format it as a digest with sections for PRs and emails.+ If nothing was found, say so.++If an app is not connected, skip it and note it in the summary.+Be concise and actionable.`,+ });++ console.log(text);+}++sweep();+// #endregion sweep