Agent Connectors

A connector gives the agent the ability to act in the outside world: send email, send SMS, read Shopify orders, add calendar events. Every service you connect adds new tools to the agent's toolset — and every tool call passes through the policy engine.

First, a clarification: there are two kinds of connector

The word "connector" appears on two different screens in SemAgent. Confusing them is the most common mistake.

There is a third screen too: Social media connectors (/settings/social-connectors) — a separate system behind its own flag.

How to connect a service

1. Open Admin panel → Settings → Connectors. Cards are split into Featured and More tabs.
2. Click a card. The dialog shows the service description, the tools it will unlock, setup notes and the required fields.
3. Fill in the fields and press Connect. Credentials are written, encrypted, to the Agent Vault.
4. Press Test to verify it live. Tests have no side effects — the SMTP test, for instance, connects and authenticates but does not send mail.

A connected card gets a green Connected badge. You can later update fields via Reconfigure, or remove it with Disconnect.

Multiple accounts on the same service

You are not stuck with one account per service. You can connect several accounts to the same connector and give each one a nickname — e.g. "Main Account", "Accounting". You use that name when you talk to the agent:

List this week's orders using the Main Account account

Tools take an account parameter for this (account="Main Account"); the agent matches the nickname itself.

Where does the inherited account's name come from? It is derived from the connection's real identity: an email address, a store domain, and so on. If there is no identity to derive one from, it is named after the service ("Existing Google"); if the identity is nothing but a number, the service name is prefixed ("Etsy 63288487"). The name isn't fixed — change it to whatever you like with the inline pencil; the agent uses the name you give it.

A Gmail connection made with your own OAuth app is detected as well — an app password or IMAP is not required for it to be carried over.

What it looks like in the panel

On the Connectors screen each service is a single card, and inside it sits the list of accounts connected to that service. Every row has:

• Nickname — the name you say to the agent.
• Credentials entered badge — are this account's credentials in the Vault?
• "existing" badge — a connection carried over from before multiple accounts (see the note above).
• Default star — the account used when the request is ambiguous.
• Enable / disable — takes an account out of play without deleting it; a disabled account is invisible to the agent.
• Edit (pencil) — changes the name and credentials of that one account.
• Delete — removes the account record.

To add one, use Add account inside the card: type the nickname, fill in the service's fields, verify it live with Test.

Why inline editing? The card-level Reconfigure button was ambiguous once several accounts existed — it wasn't clear which one it changed. So every account now has its own pencil, and an edit always applies to exactly one account.

The add-account form: every field is explained

The form shows a label plus an explanation, not raw technical key names (like drive_oauth_client_id): which value is wanted, where to get it and the expected format. Example — a Google Drive (read) account:

• What's wanted is the full contents of the service-account JSON file — not a file path and not an email address. It's a multi-line field and the content starts with {.
• On a personal Drive you must share the folder you want read with the client_email address found inside that JSON; an unshared folder is invisible to the service account.

Which services support it?

Vault-token services (like Printify and Notion) already supported multiple identities: store the secrets in the Vault under different names and tell the agent which one to use by its auth_secret name.

Connection types

Every connector has a connection type. It determines what happens behind the scenes and what counts as "connected".

Connectors you can connect today

The following are working — you can connect and test them from the panel. The "Tools unlocked" column lists what the agent can use afterwards.

E-commerce

• How do I connect Shopify? Enter your store domain (store.myshopify.com) and press Connect. Storefront MCP tools unlock — catalog search, read-only.
• How do I connect Shopify (Admin API)? Enter the store domain, Client ID and Client Secret. The shopify_query (read) and shopify_mutation (write) tools unlock.
• How do I connect Printify? Enter your Printify API token. The agent reaches the Printify API through http_request (products, shops, orders).
• How do I connect Etsy? Enter your Etsy API keystring. That's enough for reading; writing on behalf of a shop additionally requires OAuth.

Messaging

• How do I connect Email (SMTP)? Enter the SMTP host, port, username, password and from address. The agent can then send email with email_send.
• How do I connect SMS (Twilio)? Enter the Account SID, Auth Token and the sender number you bought from Twilio. sms_send and call_make unlock.
• How do I connect SMS (NetGSM)? Enter your NetGSM user code, password and your approved message header. sms_send unlocks.
• How do I connect WhatsApp Business (official)? Enter the Phone Number ID from your Meta app and a permanent (system-user) access token. whatsapp_send unlocks.
• How do I connect WhatsApp (QR session)? Generate a QR on the card and scan it from your phone. whatsapp_qr_send unlocks.

SMTP: with Gmail you must enable 2-Step Verification and generate an App Password; your normal account password will not work.

NetGSM: the message header must be approved on the NetGSM side. The test verifies your credentials against the balance endpoint.

Twilio: the same account powers both sms_send and call_make. Voice calling is the highest-risk channel and always requires approval.

WhatsApp: two paths, very different consequences

Official (Cloud API): requires Meta Business verification, a WhatsApp number, and an approved template for business-initiated messages. Verification can take weeks — start early. The 24-hour rule: if the customer wrote to you, free-form text is allowed; if you start the conversation, an approved template is mandatory.

QR session: on your phone, open WhatsApp → Settings → Linked Devices → Link a Device and scan the QR. The code refreshes roughly every 20 seconds and connects automatically once scanned.

Google

• How do I connect Google Drive? Paste your OAuth access token or your service-account JSON. drive_read unlocks.
• How do I connect Google Drive Upload (drive.file)? Create an OAuth client in your own Google Cloud project (BYOC), save the Client ID + Client Secret, then press "Connect with Google (for this account)" on the account's row and approve the drive.file permission — the refresh token is generated and written to that account, so you don't have to produce one by hand (the field is optional). drive_upload unlocks — putting email attachments and files the agent generated into Drive requires this connection.
• How do I connect Google Calendar? Enter an OAuth access token or a service-account JSON. calendar_list_events and calendar_create_event unlock.
• How do I connect Google Calendar (your own OAuth)? Create an OAuth client in your own Google Cloud project and enter the Client ID, Client Secret and a refresh token with the calendar.events scope. Events that send invitations are created through this.
• How do I connect Gmail (IMAP + SMTP)? Enter your Gmail address and a 16-character app password. gmail_search, gmail_read, gmail_delete, gmail_forward and email_send unlock.
• How do I connect Gmail (your own OAuth)? Enter the Client ID, Client Secret and a refresh token with the gmail.modify scope.
• How do I connect Gmail (central OAuth)? You cannot — this card is "Coming soon".

Why is there no central "Sign in with Google"? Reading Gmail falls under Google's restricted scope class, which requires the platform to pass a paid annual CASA security audit. Until that lands, two alternatives work today: IMAP (app password) or your own OAuth app. Sending email already works over SMTP.

The Google Calendar card also has a default calendar (calendar_id) field. The agent uses this calendar when you ask "what's on my calendar". On a personal Gmail account: the calendar address you shared with the service account. Leave it blank and the service account's own empty calendar is used.

Productivity

How do I connect Notion? Create an internal integration in Notion, paste the token, then share the relevant pages with that integration — unshared pages are invisible to the API.

Where to get each credential (step by step)

The token / key each connector asks for is issued from that service's own console. Below are the source steps for the real, connectable connectors.

Shopify (Admin API) — Client ID + Secret

1. Go to the Shopify Dev Dashboard → Create app (in the same Shopify organization as your store).
2. From the app's Settings / Client credentials, copy the Client ID and Client secret.
3. In SemAgent's Shopify (Admin API) card, enter store domain + Client ID + Client Secret. The system fetches a short-lived token automatically (Client Credentials Grant); no App Store review is needed for your own store.

Note: the customer widget uses a separate connection for live data (OAuth or Client Credentials) — see Shopify & e-commerce.

Printify — API token

1. Sign in at printify.com → My Profile → Connections.
2. Click Generate to create a Personal Access Token and copy it.
3. Paste it into SemAgent's Printify card. Docs: developers.printify.com.

Etsy — API keystring

1. Etsy Developers → Create a New App.
2. Copy the Keystring from the app page (enough for reading; writing on behalf of a shop additionally requires OAuth2).
3. Enter it in SemAgent's Etsy card.

Notion — Internal Integration Token

1. notion.so/my-integrations → New integration.
2. Copy the Internal Integration Token (secret_… / ntn_…).
3. Share the pages you want it to reach via ••• → Connections in Notion, then enter the token in SemAgent.

SMS/Voice (Twilio) — Account SID + Auth Token + number

1. Sign in to the Twilio Console → the dashboard shows your Account SID and Auth Token (reveal the token with "Show").
2. Phone Numbers → Buy a number with SMS/voice capability — that's your "from" number.
3. Enter all three in SemAgent's SMS (Twilio) card. Docs: twilio.com/docs/sms.

SMS (NetGSM) — user code + password + header

1. Sign in to your NetGSM account. Your user code (subscriber number) and API password are in the panel/account settings (define a separate API password if needed).
2. Make sure the message header you'll send from (e.g. COMPANYNAME) is approved in NetGSM — SMS won't go out with an unapproved header.
3. Enter all three in SemAgent's SMS (NetGSM) card. Docs: netgsm.com.tr/dokuman.

WhatsApp Business (official) — Phone Number ID + token

1. Create an app on Meta for Developers → add the WhatsApp product.
2. On the API Setup screen, copy the numeric Phone Number ID.
3. For lasting access, create a System User and generate a permanent token with the whatsapp_business_messaging permission (temporary tokens expire in 24h).
4. Meta Business verification + (for business-initiated messages) an approved template are required — this can take weeks, start early. Guide: Cloud API get started.

Google (Drive/Calendar/Gmail — your own OAuth) — refresh token

1. Google Cloud Console → Enable the relevant API (Gmail / Google Calendar / Drive).
2. Credentials → Create credentials → OAuth client ID to create an OAuth 2.0 client; note the Client ID + Secret.
3. OAuth Playground → gear → "Use your own OAuth credentials" → enter Client ID/Secret → pick the scope you need (gmail.modify / calendar.events / drive.readonly) → Authorize → Exchange authorization code for tokens → copy the returned refresh token.
4. Drive Upload doesn't need this step: save the Client ID + Secret and press "Connect with Google (for this account)" on the account's row; the drive.file-scoped token is generated for you.
5. Enter Client ID + Secret + refresh token in the matching SemAgent card. In "Testing" mode no CASA is required (100 users / 7-day token limit).

Gmail (IMAP) — app password

1. Google Account → Security → enable 2-Step Verification (required).
2. In the same area, App passwords → create a new one → copy the 16-character password.
3. Enter your Gmail address + this 16-char password in SemAgent's Gmail (IMAP + SMTP) card (your normal account password won't work).

Connectors marked "Coming soon"

Some cards in the catalog carry a Coming soon badge. These do not auto-connect: instead of a Connect button you get an explanation. A card being visible does not mean it can be connected.

Concretely: Slack cannot be connected, Meta Ads cannot be connected, Google Ads cannot be connected, Microsoft 365 cannot be connected, Canva cannot be connected, Stripe cannot be connected. All of them are "Coming soon".

The full list of services marked "Coming soon" (none of them auto-connect): Gmail (central OAuth), Canva, Higgsfield, Meta (Facebook/Instagram), Meta Ads, Google Ads, Microsoft 365, Slack, Stripe, Cloudflare, Klaviyo, Hugging Face, Twilio (generic card), Booking.com, Turkish Airlines, Kiwi.com, Uber, Trivago, GoDaddy, Mercury, PDF Viewer, Control Chrome, Apify, Blender, Autodesk Fusion, ElevenLabs. The first six are listed on the Featured tab, the rest on More.

Can you still use them? Yes — by approving

Here is how to use a "Coming soon" service today:

1. Add the service's API key to the Agent Vault (e.g. slack_token).
2. Tell the agent what you want. It calls the service through the general-purpose http_request tool, referring to the secret by name.
3. Because the target domain is not on your egress list, the request is not blocked — it goes to approval. Approve the card and it runs.

The egress allow-list: domain permissions

The domains your agent may reach are kept in a per-tenant egress list. It fills up in two ways:

• When you connect a catalog connector — the service's domain is added automatically (catalog entries are pre-vetted).
• When you save the WoopSocial social connector — api.woopsocial.com is added automatically.

Beyond that, there is no tenant screen for adding domains by hand; extra domains are defined by the platform administrator.

For a target that is not on the list, behaviour differs by layer — don't conflate them:

Disconnecting

What happens on disconnect depends on the type — especially for secrets:

• smtp and fields → the field secrets are deleted from the Vault.
• mcp → the MCP server registration is removed.
• rest and oauth_google → the domain leaves the egress list, but the token stays in the Vault. Delete it manually from the Vault if you want it gone.