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 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.")