Workplace search agent - Composio

View source on GitHub

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

Project setup

bash

mkdir composio-workplace-search && cd composio-workplace-search
uv init && uv add composio composio-openai-agents openai-agents

bash

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 once locally before deploying `agent.py` to a CI pipeline or scheduled job. </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

authorize.py connects each toolkit via OAuth using session.authorize() and wait_for_connection(). It checks session.toolkits() first to skip already-connected apps.
The session is created with four toolkits. Composio scopes all tool calls to the user's connected accounts.
The agent searches across apps, synthesizes results, and cites sources with links, channel names, or sender info.
The USER_ID in .env scopes all connections — swap it to switch users without changing code.

Take it further

The prompt and toolkits are the only moving parts. Change them to change what the agent searches:

Engineering on-call: add PagerDuty and Datadog toolkits, ask "what incidents fired overnight and which PRs might be related?"
Sales prep: connect Salesforce and Gmail, ask "summarize all recent activity with Acme Corp before my call"
Compliance audit: add Jira and Confluence, ask "which security tickets are still open and do any docs reference the old auth flow?"