Skip to content

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

Sushmitha Mallesha48a23bc7ba1
diff --git a/docs/.claude/plan.md b/docs/.claude/plan.md
index 020e45195..d40f65144 100644
--- a/docs/.claude/plan.md
+++ b/docs/.claude/plan.md
@@ -97,9 +97,9 @@
- [x] `chat-app` — Build a Chat App (PR #2728, branch: `docs/chat-app-1`)
- [ ] `slack-bot` — Build a Slack Bot (Vercel AI SDK + Composio)
-- [ ] `pr-review-agent` — Build a PR Review Agent (GitHub)
-- [ ] `gmail-auto-labeler` — Build a Gmail Auto-Labeler (Gmail)
-- [ ] `slack-summarizer` — Build a Slack Channel Summarizer (Slack)
+- [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)
+- [x] `gmail-auto-labeler` — Already exists as `gmail-labeler` cookbook
+- [x] `slack-summarizer` — Already exists as `slack-summariser` cookbook
- [ ] `mcp-setup` — Connect Composio Tools via MCP
- [ ] `research-agent` — Build a Research Agent (Web Search, Scraping)
@@ -184,7 +184,7 @@ Full-stack templates live as cloneable repos on GitHub. Docs pages describe what
| 1.0 Rename Examples → Cookbooks | ✅ Done |
| 1.1 Provider Pages | ✅ Done (except `langgraph.mdx`) |
| 1.2–1.5 Structure & Index | Deferred |
-| 2 Use-Case Cookbooks | In progress (1 done, 17 remaining) |
+| 2 Use-Case Cookbooks | In progress (4 done, 14 remaining) |
| 3 Framework Cookbooks | Not started (11 cookbooks) |
| 4 Polish | Not started |
| 5 Index Page Revamp | Not started |
diff --git a/docs/content/cookbooks/index.mdx b/docs/content/cookbooks/index.mdx
index 3818ae950..df2a6bbe8 100644
--- a/docs/content/cookbooks/index.mdx
+++ b/docs/content/cookbooks/index.mdx
@@ -32,6 +32,7 @@ Browse open-source templates or follow step-by-step guides below.
<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" />
<Card title="Supabase SQL Agent" href="/cookbooks/supabase-sql-agent" description="Execute SQL queries using natural language" />
+ <Card title="Workplace Search Agent" href="/cookbooks/workplace-search" description="Search across GitHub, Slack, Gmail, and Notion from a single agent" />
</Cards>
## Behind the Curtain
diff --git a/docs/content/cookbooks/meta.json b/docs/content/cookbooks/meta.json
index 211f804c8..62dda3288 100644
--- a/docs/content/cookbooks/meta.json
+++ b/docs/content/cookbooks/meta.json
@@ -16,6 +16,7 @@
"gmail-labeler",
"slack-summariser",
"supabase-sql-agent",
+ "workplace-search",
"---Behind the Curtain---",
"tool-generator"
]
diff --git a/docs/content/cookbooks/workplace-search.mdx b/docs/content/cookbooks/workplace-search.mdx
new file mode 100644
index 000000000..55b5e1bbe
--- /dev/null
+++ b/docs/content/cookbooks/workplace-search.mdx
@@ -0,0 +1,122 @@
+---
+title: Workplace search agent
+description: Search across GitHub, Slack, Gmail, and Notion from a single agent
+---
+
+[View source on GitHub](https://github.com/ComposioHQ/composio/tree/next/docs/examples/workplace-search)
+
+Build a search agent that queries across your workplace tools and returns answers with citations. One session, four toolkits.
+
+## What you'll learn
+
+- **Manual authentication**: connect multiple apps with `session.authorize()` and `wait_for_connection()`
+- **Multi-toolkit sessions**: one session spanning GitHub, Slack, Gmail, and Notion
+- **Cross-app search**: agent decides which apps to query based on the question
+
+## Prerequisites
+
+- Python 3.10+
+- [UV](https://docs.astral.sh/uv/getting-started/installation/)
+- [Composio API key](https://platform.composio.dev/settings)
+- [OpenAI API key](https://platform.openai.com/api-keys)
+
+## Project setup
+
+```bash
+mkdir composio-workplace-search && cd composio-workplace-search
+uv init && uv add composio composio-openai-agents openai-agents
+```
+
+```bash title=".env"
+COMPOSIO_API_KEY=your_composio_api_key
+OPENAI_API_KEY=your_openai_api_key
+USER_ID=a1b2c3d4-e5f6-7890-abcd-ef1234567890
+```
+
+## File structure
+
+```
+composio-workplace-search/
+ authorize.py # One-time: connect GitHub, Slack, Gmail, Notion
+ agent.py # The search agent
+ .env
+```
+
+## Step 1: Connect your apps
+
+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.
+
+<include>../../examples/workplace-search/authorize.py</include>
+
+Run it once:
+
+```bash
+uv run --env-file .env python authorize.py
+```
+
+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.
+
+<Callout>
+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.
+</Callout>
+
+## Step 2: Build the agent
+
+### Setting up the client
+
+<include>../../examples/workplace-search/agent.py#setup</include>
+
+### The system prompt
+
+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.
+
+<include>../../examples/workplace-search/agent.py#agent</include>
+
+### Running the search
+
+`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.
+
+<include>../../examples/workplace-search/agent.py#search</include>
+
+## Running the agent
+
+```bash
+uv run --env-file .env python agent.py "What decisions were made about the v2 migration?"
+```
+
+Or start it interactively:
+
+```bash
+uv run --env-file .env python agent.py
+```
+
+Example output:
+
+```
+Based on my search across your connected apps:
+
+**GitHub**: PR #412 "v2 migration plan" (merged Feb 15) outlines the database
+schema changes. Issue #389 tracks the remaining blockers.
+(Source: github.com/acme/backend/pull/412)
+
+**Slack**: In #engineering on Feb 14, @alice proposed splitting the migration
+into two phases. The team agreed in the thread.
+(Source: #engineering, Feb 14)
+
+**Gmail**: No relevant emails found for "v2 migration".
+
+**Notion**: Skipped (not connected)
+```
+
+## How it works
+
+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.
+2. The session is created with four toolkits. Composio scopes all tool calls to the user's connected accounts.
+3. The agent searches across apps, synthesizes results, and cites sources with links, channel names, or sender info.
+4. Changing `USER_ID` in `.env` switches to a different user's connections without touching the code.
+
+## Next steps
+
+- Restrict to read-only tools with `tags` when creating the session. See [Enable and disable toolkits](/docs/toolkits/enable-and-disable-toolkits).
+- Wrap this in a FastAPI endpoint and pass `user_id` from your auth middleware.
+- Add more toolkits (Jira, Confluence, Linear) without changing the agent code.
diff --git a/docs/examples/workplace-search/agent.py b/docs/examples/workplace-search/agent.py
new file mode 100644
index 000000000..54c725d5c
--- /dev/null
+++ b/docs/examples/workplace-search/agent.py
@@ -0,0 +1,59 @@
+# region setup
+import asyncio
+import os
+import sys
+
+from agents import Agent, Runner
+from composio import Composio
+from composio_openai_agents import OpenAIAgentsProvider
+
+composio = Composio(provider=OpenAIAgentsProvider())
+# endregion setup
+
+
+# region agent
+SYSTEM_PROMPT = """You are a workplace search agent. You have access to GitHub, Slack, Gmail, and Notion.
+
+When the user asks a question:
+1. Break it down: decide which apps to search and what to look for.
+2. Search across multiple apps in parallel when possible.
+3. Synthesize findings into a single answer with citations.
+
+For every piece of information you include, cite the source:
+- GitHub: link to the issue, PR, or file
+- Slack: channel name and date
+- Gmail: sender and subject line
+- Notion: page title
+
+If a toolkit is not connected, skip it and note which sources were unavailable.
+Do not ask for clarification. Use broad search terms and filter from the results."""
+# endregion agent
+
+
+# region search
+async def main():
+ # Set USER_ID in your .env file
+ user_id = os.environ["USER_ID"]
+
+ session = composio.create(
+ user_id=user_id,
+ toolkits=["github", "slack", "gmail", "notion"],
+ )
+
+ tools = session.tools()
+
+ agent = Agent(
+ name="Workplace Search",
+ model="gpt-4.1",
+ instructions=SYSTEM_PROMPT,
+ tools=tools,
+ )
+
+ query = " ".join(sys.argv[1:]) if len(sys.argv) > 1 else input("\nSearch: ")
+ result = await Runner.run(starting_agent=agent, input=query)
+
+ print(result.final_output)
+# endregion search
+
+
+asyncio.run(main())
diff --git a/docs/examples/workplace-search/authorize.py b/docs/examples/workplace-search/authorize.py
new file mode 100644
index 000000000..eebaea7a3
--- /dev/null
+++ b/docs/examples/workplace-search/authorize.py
@@ -0,0 +1,36 @@
+"""
+One-time setup: connect your GitHub, Slack, Gmail, and Notion accounts.
+Run this once before using the search agent.
+"""
+
+import os
+
+from composio import Composio
+
+composio = Composio()
+
+# Set USER_ID in your .env file
+user_id = os.environ["USER_ID"]
+
+session = composio.create(
+ user_id=user_id,
+ toolkits=["github", "slack", "gmail", "notion"],
+)
+
+# Authorize each toolkit one at a time
+for toolkit in ["github", "slack", "gmail", "notion"]:
+ print(f"\n--- {toolkit.upper()} ---")
+
+ # Check if already connected
+ status = session.toolkits(toolkits=[toolkit])
+ if status.items and status.items[0].connection and status.items[0].connection.is_active:
+ print(f"Already connected.")
+ continue
+
+ connection = session.authorize(toolkit)
+ print(f"Open this URL to connect:\n{connection.redirect_url}")
+
+ connected = connection.wait_for_connection()
+ print(f"Connected: {connected.id}")
+
+print("\nAll done. Run agent.py to start searching.")