Agent Teams#

A TypeScript CLI tool that enables AI agents and humans to interact with Microsoft Teams through a simple command interface. Features seamless token extraction from the Teams desktop app and multi-team support.

Quick Start#

bash

# Get team snapshot (credentials are extracted automatically)
agent-teams snapshot

# Send a message
agent-teams message send <team-id> <channel-id> "Hello from AI agent!"

# List channels
agent-teams channel list <team-id>

Authentication#

Credentials are extracted automatically from the Teams desktop app on first use. No manual setup required — just run any command and authentication happens silently in the background.

Teams tokens expire in 60-90 minutes. The CLI automatically re-extracts a fresh token when the current one expires, so you don't need to manage token lifecycle manually.

IMPORTANT: NEVER guide the user to open a web browser, use DevTools, or manually copy tokens from a browser. Always use agent-teams auth extract to obtain tokens from the desktop app.

Multi-Team Support#

bash

# List all available teams
agent-teams team list

# Switch to a different team
agent-teams team switch <team-id>

# Show current team
agent-teams team current

# Check auth status (includes token expiry info)
agent-teams auth status

Multi-Account Support (Work / Personal)#

bash

# Switch between work and personal accounts
agent-teams auth switch-account work
agent-teams auth switch-account personal

# Use a specific account for one command (without switching)
agent-teams snapshot --account work

Memory#

The agent maintains a ~/.config/agent-messenger/MEMORY.md file as persistent memory across sessions. This is agent-managed — the CLI does not read or write this file. Use the Read and Write tools to manage your memory file.

Reading Memory#

At the start of every task, read ~/.config/agent-messenger/MEMORY.md using the Read tool to load any previously discovered team IDs, channel IDs, user IDs, and preferences.

• If the file doesn't exist yet, that's fine — proceed without it and create it when you first have useful information to store.
• If the file can't be read (permissions, missing directory), proceed without memory — don't error out.

Writing Memory#

After discovering useful information, update ~/.config/agent-messenger/MEMORY.md using the Write tool. Write triggers include:

• After discovering team IDs and names (from team list, snapshot, etc.)
• After discovering useful channel IDs and names (from channel list, snapshot, etc.)
• After discovering user IDs and names (from user list, user me, etc.)
• After the user gives you an alias or preference ("call this the standup channel", "my main team is X")
• After discovering channel structure (standard vs private channels)

When writing, include the complete file content — the Write tool overwrites the entire file.

What to Store#

• Team IDs with names
• Channel IDs with names and team context
• User IDs with display names
• User-given aliases ("standup channel", "main team")
• Account preferences (work vs personal)
• Any user preference expressed during interaction

What NOT to Store#

Never store tokens, credentials, or any sensitive data. Never store full message content (just IDs and channel context). Never store file upload contents.

Handling Stale Data#

If a memorized ID returns an error (channel not found, team not found), remove it from MEMORY.md. Don't blindly trust memorized data — verify when something seems off. Prefer re-listing over using a memorized ID that might be stale.

Format / Example#

markdown

# Agent Messenger Memory

## Teams

- `team-id-1` — Acme Corp (default, work account)
- `team-id-2` — Side Project (personal account)

## Channels (Acme Corp)

- `channel-id-1` — General
- `channel-id-2` — Engineering
- `channel-id-3` — Standups

## Users (Acme Corp)

- `user-id-1` — Alice (engineering lead)
- `user-id-2` — Bob (backend)

## Aliases

- "standup" → `channel-id-3` (Standups in Acme Corp)
- "main team" → `team-id-1` (Acme Corp)

## Notes

- User prefers work account by default
- Main team is "Acme Corp"

Memory lets you skip repeated channel list and team list calls. When you already know an ID from a previous session, use it directly.

Commands#

Auth Commands#

bash

# Extract token from Teams desktop app (usually automatic)
agent-teams auth extract
agent-teams auth extract --debug

# Check auth status (includes token expiry info)
agent-teams auth status

# Logout from Microsoft Teams
agent-teams auth logout

# Switch between work and personal accounts
agent-teams auth switch-account <account-type>
agent-teams auth switch-account work
agent-teams auth switch-account personal

Message Commands#

bash

# Send a message
agent-teams message send <team-id> <channel-id> <content>
agent-teams message send <team-id> 19:abc123@thread.tacv2 "Hello world"

# List messages
agent-teams message list <team-id> <channel-id>
agent-teams message list <team-id> 19:abc123@thread.tacv2 --limit 50

# Get a single message by ID
agent-teams message get <team-id> <channel-id> <message-id>

# Delete a message
agent-teams message delete <team-id> <channel-id> <message-id> --force

Channel Commands#

bash

# List channels in a team
agent-teams channel list <team-id>

# Get channel info
agent-teams channel info <team-id> <channel-id>
agent-teams channel info <team-id> 19:abc123@thread.tacv2

# Get channel history (alias for message list)
agent-teams channel history <team-id> <channel-id> --limit 100

Team Commands#

bash

# List all teams
agent-teams team list

# Get team info
agent-teams team info <team-id>

# Switch active team
agent-teams team switch <team-id>

# Show current team
agent-teams team current

# Remove a team from config
agent-teams team remove <team-id>

User Commands#

bash

# List team members
agent-teams user list <team-id>

# Get user info
agent-teams user info <user-id>

# Get current user
agent-teams user me

Reaction Commands#

bash

# Add reaction (use emoji name)
agent-teams reaction add <team-id> <channel-id> <message-id> <emoji>
agent-teams reaction add <team-id> 19:abc123@thread.tacv2 1234567890 like

# Remove reaction
agent-teams reaction remove <team-id> <channel-id> <message-id> <emoji>

File Commands#

bash

# Upload file
agent-teams file upload <team-id> <channel-id> <path>
agent-teams file upload <team-id> 19:abc123@thread.tacv2 ./report.pdf

# List files in channel
agent-teams file list <team-id> <channel-id>

# Get file info
agent-teams file info <team-id> <channel-id> <file-id>

Snapshot Command#

Get comprehensive team state for AI agents:

bash

# Full snapshot
agent-teams snapshot

# Filtered snapshots
agent-teams snapshot --channels-only
agent-teams snapshot --users-only

# Limit messages per channel
agent-teams snapshot --limit 10

Returns JSON with:

• Team metadata (id, name)
• Channels (id, name, type, description)
• Recent messages (id, content, author, timestamp)
• Members (id, displayName, email)

Output Format#

JSON (Default)#

All commands output JSON by default for AI consumption:

json

{
  "id": "19:abc123@thread.tacv2",
  "content": "Hello world",
  "author": "John Doe",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Pretty (Human-Readable)#

Use --pretty flag for formatted output:

bash

agent-teams channel list --pretty

Key Differences from Discord/Slack#

FeatureTeamsDiscordSlackServer terminologyTeamGuildWorkspaceChannel identifiersUUID format (19:xxx@thread.tacv2)Snowflake IDsChannel name or IDToken storageCookies SQLiteLevelDBLevelDBToken expiry60-90 minutesRarely expiresRarely expiresMentions<at id="user-id">Name</at>``<@user_id>``<@USER_ID>

Important: Teams uses UUID-style channel IDs (like 19:abc123@thread.tacv2). You cannot use channel names directly - use channel list to find IDs first.

Common Patterns#

See references/common-patterns.md for typical AI agent workflows.

Templates#

See templates/ directory for runnable examples:

• post-message.sh - Send messages with error handling
• monitor-channel.sh - Monitor channel for new messages (with token refresh)
• team-summary.sh - Generate team summary

Error Handling#

All commands return consistent error format:

json

{
  "error": "Not authenticated. Run \"auth extract\" first."
}

Common errors:

• Not authenticated: No valid token (auto-extraction failed — see Troubleshooting)
• Token expired: Token has expired and auto-refresh failed — see Troubleshooting
• No current team set: Run team switch <id> first
• Message not found: Invalid message ID
• Channel not found: Invalid channel ID
• 401 Unauthorized: Token expired and auto-refresh failed — see Troubleshooting

Configuration#

Credentials stored in: ~/.config/agent-messenger/teams-credentials.json

Format:

json

{
  "token": "skypetoken_asm_value_here",
  "token_extracted_at": "2024-01-15T10:00:00.000Z",
  "current_team": "team-uuid-here",
  "teams": {
    "team-uuid-here": {
      "team_id": "team-uuid-here",
      "team_name": "My Team"
    }
  }
}

Security: File permissions set to 0600 (owner read/write only)

Limitations#

• No real-time events / WebSocket connection
• No voice/video channel support
• No team management (create/delete channels, roles)
• No meeting support
• No webhook support
• Plain text messages only (no adaptive cards in v1)
• User tokens only (no app tokens)
• Token expires in 60-90 minutes - auto-refreshed, but requires Teams desktop app to be logged in

Troubleshooting#

Authentication fails or token expired#

Credentials and token refresh are normally handled automatically. If auto-extraction fails, run it manually with debug output:

bash

agent-teams auth extract --debug

Common causes:

• Teams desktop app is not installed or not logged in
• Teams Cookies database is locked or inaccessible
• Token expired and Teams desktop app session also expired (re-login to Teams)

agent-teams: command not found#

agent-teams is NOT the npm package name. The npm package is agent-messenger.

If the package is installed globally, use agent-teams directly:

bash

agent-teams team list

If the package is NOT installed, use bunx agent-messenger teams:

bash

bunx agent-messenger teams team list

NEVER run bunx agent-teams — it will fail or install a wrong package since agent-teams is not the npm package name.

References#

• Authentication Guide
• Common Patterns