@devries-cameron20 / composio Mirror · read-only / commits / a48a23bc7
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, 03:15 UTC

docs: add workplace search agent cookbook

Multi-toolkit session cookbook that searches across GitHub, Slack, Gmail, and Notion. Teaches manual auth flow with session.authorize() and wait_for_connection(). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Sushmitha Mallesh committed Mar 11, 2026 at 01:47 UTC a48a23bc7ba1e72d55878fb1438d1f50d3ec1aa2
6 files changed +223 -4
docs/.claude/plan.md
+4 -4
@@ -97,9 +97,9 @@
97
98 - [x] `chat-app` — Build a Chat App (PR #2728, branch: `docs/chat-app-1`)
99 - [ ] `slack-bot` — Build a Slack Bot (Vercel AI SDK + Composio)
100 -- [ ] `pr-review-agent` — Build a PR Review Agent (GitHub)
101 -- [ ] `gmail-auto-labeler` — Build a Gmail Auto-Labeler (Gmail)
102 -- [ ] `slack-summarizer` — Build a Slack Channel Summarizer (Slack)
100 +- [x] `pr-review-agent` — PR review agent (PR #2832, branch: `docs/pr-review-agent-cookbook`, OpenAI Agents SDK, reads CLAUDE.md/AGENTS.md, includes GitHub Action)
101 +- [x] `gmail-auto-labeler` — Already exists as `gmail-labeler` cookbook
102 +- [x] `slack-summarizer` — Already exists as `slack-summariser` cookbook
103 - [ ] `mcp-setup` — Connect Composio Tools via MCP
104 - [ ] `research-agent` — Build a Research Agent (Web Search, Scraping)
105
@@ -184,7 +184,7 @@ Full-stack templates live as cloneable repos on GitHub. Docs pages describe what
184 | 1.0 Rename Examples → Cookbooks | ✅ Done |
185 | 1.1 Provider Pages | ✅ Done (except `langgraph.mdx`) |
186 | 1.2–1.5 Structure & Index | Deferred |
187 -| 2 Use-Case Cookbooks | In progress (1 done, 17 remaining) |
187 +| 2 Use-Case Cookbooks | In progress (4 done, 14 remaining) |
188 | 3 Framework Cookbooks | Not started (11 cookbooks) |
189 | 4 Polish | Not started |
190 | 5 Index Page Revamp | Not started |
docs/content/cookbooks/index.mdx
+1
@@ -32,6 +32,7 @@ Browse open-source templates or follow step-by-step guides below.
32 <Card title="Gmail Labeler" href="/cookbooks/gmail-labeler" description="Automatically label incoming emails using triggers" />
33 <Card title="Slack Summarizer" href="/cookbooks/slack-summariser" description="Summarize Slack channel messages" />
34 <Card title="Supabase SQL Agent" href="/cookbooks/supabase-sql-agent" description="Execute SQL queries using natural language" />
35 + <Card title="Workplace Search Agent" href="/cookbooks/workplace-search" description="Search across GitHub, Slack, Gmail, and Notion from a single agent" />
36 </Cards>
37
38 ## Behind the Curtain
docs/content/cookbooks/meta.json
+1
@@ -16,6 +16,7 @@
16 "gmail-labeler",
17 "slack-summariser",
18 "supabase-sql-agent",
19 + "workplace-search",
20 "---Behind the Curtain---",
21 "tool-generator"
22 ]
docs/content/cookbooks/workplace-search.mdx new
+122
@@ -0,0 +1,122 @@
1 +---
2 +title: Workplace search agent
3 +description: Search across GitHub, Slack, Gmail, and Notion from a single agent
4 +---
5 +
6 +[View source on GitHub](https://github.com/ComposioHQ/composio/tree/next/docs/examples/workplace-search)
7 +
8 +Build a search agent that queries across your workplace tools and returns answers with citations. One session, four toolkits.
9 +
10 +## What you'll learn
11 +
12 +- **Manual authentication**: connect multiple apps with `session.authorize()` and `wait_for_connection()`
13 +- **Multi-toolkit sessions**: one session spanning GitHub, Slack, Gmail, and Notion
14 +- **Cross-app search**: agent decides which apps to query based on the question
15 +
16 +## Prerequisites
17 +
18 +- Python 3.10+
19 +- [UV](https://docs.astral.sh/uv/getting-started/installation/)
20 +- [Composio API key](https://platform.composio.dev/settings)
21 +- [OpenAI API key](https://platform.openai.com/api-keys)
22 +
23 +## Project setup
24 +
25 +```bash
26 +mkdir composio-workplace-search && cd composio-workplace-search
27 +uv init && uv add composio composio-openai-agents openai-agents
28 +```
29 +
30 +```bash title=".env"
31 +COMPOSIO_API_KEY=your_composio_api_key
32 +OPENAI_API_KEY=your_openai_api_key
33 +USER_ID=a1b2c3d4-e5f6-7890-abcd-ef1234567890
34 +```
35 +
36 +## File structure
37 +
38 +```
39 +composio-workplace-search/
40 + authorize.py # One-time: connect GitHub, Slack, Gmail, Notion
41 + agent.py # The search agent
42 + .env
43 +```
44 +
45 +## Step 1: Connect your apps
46 +
47 +Before the agent can search, each toolkit needs an active connection. `authorize.py` walks through them one by one, skipping any that are already connected.
48 +
49 +<include>../../examples/workplace-search/authorize.py</include>
50 +
51 +Run it once:
52 +
53 +```bash
54 +uv run --env-file .env python authorize.py
55 +```
56 +
57 +Each toolkit prints a URL. Open it in a browser, complete OAuth, and the script moves to the next one. You only need to do this once per user.
58 +
59 +<Callout>
60 +If you're using sessions with meta tools (`COMPOSIO_MANAGE_CONNECTIONS`), authentication happens in-chat automatically. This manual flow is useful when you want to pre-connect apps before the agent runs, like in a setup script or CI pipeline.
61 +</Callout>
62 +
63 +## Step 2: Build the agent
64 +
65 +### Setting up the client
66 +
67 +<include>../../examples/workplace-search/agent.py#setup</include>
68 +
69 +### The system prompt
70 +
71 +The prompt tells the agent to search across apps, synthesize findings, and cite every source. If a toolkit isn't connected, it skips it instead of failing.
72 +
73 +<include>../../examples/workplace-search/agent.py#agent</include>
74 +
75 +### Running the search
76 +
77 +`session.tools()` returns provider-wrapped tools ready for the OpenAI Agents SDK. The `USER_ID` from your `.env` file scopes all connections to that user.
78 +
79 +<include>../../examples/workplace-search/agent.py#search</include>
80 +
81 +## Running the agent
82 +
83 +```bash
84 +uv run --env-file .env python agent.py "What decisions were made about the v2 migration?"
85 +```
86 +
87 +Or start it interactively:
88 +
89 +```bash
90 +uv run --env-file .env python agent.py
91 +```
92 +
93 +Example output:
94 +
95 +```
96 +Based on my search across your connected apps:
97 +
98 +**GitHub**: PR #412 "v2 migration plan" (merged Feb 15) outlines the database
99 +schema changes. Issue #389 tracks the remaining blockers.
100 +(Source: github.com/acme/backend/pull/412)
101 +
102 +**Slack**: In #engineering on Feb 14, @alice proposed splitting the migration
103 +into two phases. The team agreed in the thread.
104 +(Source: #engineering, Feb 14)
105 +
106 +**Gmail**: No relevant emails found for "v2 migration".
107 +
108 +**Notion**: Skipped (not connected)
109 +```
110 +
111 +## How it works
112 +
113 +1. `authorize.py` connects each toolkit via OAuth using `session.authorize()` and `wait_for_connection()`. It checks `session.toolkits()` first to skip already-connected apps.
114 +2. The session is created with four toolkits. Composio scopes all tool calls to the user's connected accounts.
115 +3. The agent searches across apps, synthesizes results, and cites sources with links, channel names, or sender info.
116 +4. Changing `USER_ID` in `.env` switches to a different user's connections without touching the code.
117 +
118 +## Next steps
119 +
120 +- Restrict to read-only tools with `tags` when creating the session. See [Enable and disable toolkits](/docs/toolkits/enable-and-disable-toolkits).
121 +- Wrap this in a FastAPI endpoint and pass `user_id` from your auth middleware.
122 +- Add more toolkits (Jira, Confluence, Linear) without changing the agent code.
docs/examples/workplace-search/agent.py new
+59
@@ -0,0 +1,59 @@
1 +# region setup
2 +import asyncio
3 +import os
4 +import sys
5 +
6 +from agents import Agent, Runner
7 +from composio import Composio
8 +from composio_openai_agents import OpenAIAgentsProvider
9 +
10 +composio = Composio(provider=OpenAIAgentsProvider())
11 +# endregion setup
12 +
13 +
14 +# region agent
15 +SYSTEM_PROMPT = """You are a workplace search agent. You have access to GitHub, Slack, Gmail, and Notion.
16 +
17 +When the user asks a question:
18 +1. Break it down: decide which apps to search and what to look for.
19 +2. Search across multiple apps in parallel when possible.
20 +3. Synthesize findings into a single answer with citations.
21 +
22 +For every piece of information you include, cite the source:
23 +- GitHub: link to the issue, PR, or file
24 +- Slack: channel name and date
25 +- Gmail: sender and subject line
26 +- Notion: page title
27 +
28 +If a toolkit is not connected, skip it and note which sources were unavailable.
29 +Do not ask for clarification. Use broad search terms and filter from the results."""
30 +# endregion agent
31 +
32 +
33 +# region search
34 +async def main():
35 + # Set USER_ID in your .env file
36 + user_id = os.environ["USER_ID"]
37 +
38 + session = composio.create(
39 + user_id=user_id,
40 + toolkits=["github", "slack", "gmail", "notion"],
41 + )
42 +
43 + tools = session.tools()
44 +
45 + agent = Agent(
46 + name="Workplace Search",
47 + model="gpt-4.1",
48 + instructions=SYSTEM_PROMPT,
49 + tools=tools,
50 + )
51 +
52 + query = " ".join(sys.argv[1:]) if len(sys.argv) > 1 else input("\nSearch: ")
53 + result = await Runner.run(starting_agent=agent, input=query)
54 +
55 + print(result.final_output)
56 +# endregion search
57 +
58 +
59 +asyncio.run(main())
docs/examples/workplace-search/authorize.py new
+36
@@ -0,0 +1,36 @@
1 +"""
2 +One-time setup: connect your GitHub, Slack, Gmail, and Notion accounts.
3 +Run this once before using the search agent.
4 +"""
5 +
6 +import os
7 +
8 +from composio import Composio
9 +
10 +composio = Composio()
11 +
12 +# Set USER_ID in your .env file
13 +user_id = os.environ["USER_ID"]
14 +
15 +session = composio.create(
16 + user_id=user_id,
17 + toolkits=["github", "slack", "gmail", "notion"],
18 +)
19 +
20 +# Authorize each toolkit one at a time
21 +for toolkit in ["github", "slack", "gmail", "notion"]:
22 + print(f"\n--- {toolkit.upper()} ---")
23 +
24 + # Check if already connected
25 + status = session.toolkits(toolkits=[toolkit])
26 + if status.items and status.items[0].connection and status.items[0].connection.is_active:
27 + print(f"Already connected.")
28 + continue
29 +
30 + connection = session.authorize(toolkit)
31 + print(f"Open this URL to connect:\n{connection.redirect_url}")
32 +
33 + connected = connection.wait_for_connection()
34 + print(f"Connected: {connected.id}")
35 +
36 +print("\nAll done. Run agent.py to start searching.")