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 workplace search agent cookbook
Sushmitha Mallesha48a23bc7ba1
diff --git a/docs/.claude/plan.md b/docs/.claude/plan.mdindex 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.mdxindex 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 Curtaindiff --git a/docs/content/cookbooks/meta.json b/docs/content/cookbooks/meta.jsonindex 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.mdxnew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.")