agent-teams

Interact with Microsoft Teams - send messages, read channels, manage reactions

Install

openclaw skills install @penglovemeng/peng-agent-teams

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

Feature	Teams	Discord	Slack
Server terminology	Team	Guild	Workspace
Channel identifiers	UUID format (19:xxx@thread.tacv2)	Snowflake IDs	Channel name or ID
Token storage	Cookies SQLite	LevelDB	LevelDB
Token expiry	60-90 minutes	Rarely expires	Rarely expires
Mentions	`<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.

agent-teams

Install

Agent Teams

Quick Start

Authentication

Multi-Team Support

Multi-Account Support (Work / Personal)

Memory

Reading Memory

Writing Memory

What to Store

What NOT to Store

Handling Stale Data

Format / Example

Commands

Auth Commands

Message Commands

Channel Commands

Team Commands

User Commands

Reaction Commands

File Commands

Snapshot Command

Output Format

JSON (Default)

Pretty (Human-Readable)

Key Differences from Discord/Slack

Common Patterns

Templates

Error Handling

Configuration

Limitations

Troubleshooting

Authentication fails or token expired

agent-teams: command not found

References

`agent-teams: command not found`