Back to Details

agent-teams

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
一款TypeScript CLI工具，让AI Agent和人类能够通过简单的命令行界面与Microsoft Teams交互。支持从Teams桌面应用中无缝提取token，并且支持多团队管理。

TOKEN EXPIRY WARNING

TOKEN过期警告

CRITICAL: Microsoft Teams tokens expire in 60-90 minutes! Unlike Discord/Slack, Teams tokens have a short lifespan. You MUST:
  1. Check token validity before operations
  2. Re-extract credentials when tokens expire
  3. Handle 
    401 Unauthorized
    errors gracefully
bash
undefined
重要提示：Microsoft Teams的token有效期为60-90分钟！与Discord/Slack不同，Teams的token寿命很短。你必须：
  1. 在操作前检查token有效性
  2. token过期时重新提取凭证
  3. 妥善处理
    401 Unauthorized
    错误
bash
undefined

Always check auth status first

始终先检查认证状态

agent-teams auth status
agent-teams auth status

If expired, re-extract

如果已过期，重新提取

agent-teams auth extract
undefined
agent-teams auth extract
undefined

Quick Start

快速开始

bash
undefined
bash
undefined

Extract credentials from Teams desktop app (zero-config)

从Teams桌面应用提取凭证（零配置）

agent-teams auth extract
agent-teams auth extract

Get team snapshot

获取团队快照

agent-teams snapshot
agent-teams snapshot

Send a message

发送消息

agent-teams message send <channel-id> "Hello from AI agent!"
agent-teams message send <channel-id> "Hello from AI agent!"

List channels

列出频道

agent-teams channel list
undefined
agent-teams channel list
undefined

Authentication

认证

Seamless Token Extraction

无缝Token提取

agent-teams automatically extracts your Teams credentials from the desktop app:
bash
undefined
agent-teams会自动从桌面应用中提取你的Teams凭证：
bash
undefined

Just run this - no manual token copying needed

只需运行此命令——无需手动复制token

agent-teams auth extract
agent-teams auth extract

Use --debug for troubleshooting

使用--debug参数进行故障排查

agent-teams auth extract --debug

This command:
- Auto-detects your platform (macOS/Linux/Windows)
- Extracts skypetoken_asm from Teams desktop app's Cookies SQLite database
- Validates token against Teams API before saving
- Discovers ALL joined teams
- Stores credentials securely in `~/.config/agent-messenger/`
agent-teams auth extract --debug

该命令：
- 自动检测你的操作系统（macOS/Linux/Windows）
- 从Teams桌面应用的Cookies SQLite数据库中提取skypetoken_asm
- 在保存前验证token是否可访问Teams API
- 发现所有已加入的团队
- 将凭证安全存储在`~/.config/agent-messenger/`目录下

Multi-Team Support

多团队支持

bash
undefined
bash
undefined

List all available teams

列出所有可用团队

agent-teams team list
agent-teams team list

Switch to a different team

切换到其他团队

agent-teams team switch <team-id>
agent-teams team switch <team-id>

Show current team

显示当前团队

agent-teams team current
agent-teams team current

Check auth status (includes token expiry info)

检查认证状态（包含token过期信息）

agent-teams auth status
undefined
agent-teams auth status
undefined

Commands

命令

Message Commands

消息命令

bash
undefined
bash
undefined

Send a message

发送消息

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

List messages

列出消息

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

Get a single message by ID

根据ID获取单条消息

agent-teams message get <channel-id> <message-id>
agent-teams message get <channel-id> <message-id>

Delete a message

删除消息

agent-teams message delete <channel-id> <message-id> --force
undefined
agent-teams message delete <channel-id> <message-id> --force
undefined

Channel Commands

频道命令

bash
undefined
bash
undefined

List channels in current team

列出当前团队的频道

agent-teams channel list
agent-teams channel list

Get channel info

获取频道信息

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

Get channel history (alias for message list)

获取频道历史消息（message list的别名）

agent-teams channel history <channel-id> --limit 100
undefined
agent-teams channel history <channel-id> --limit 100
undefined

Team Commands

团队命令

bash
undefined
bash
undefined

List all teams

列出所有团队

agent-teams team list
agent-teams team list

Get team info

获取团队信息

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

Switch active team

切换活跃团队

agent-teams team switch <team-id>
agent-teams team switch <team-id>

Show current team

显示当前团队

agent-teams team current
undefined
agent-teams team current
undefined

User Commands

用户命令

bash
undefined
bash
undefined

List team members

列出团队成员

agent-teams user list
agent-teams user list

Get user info

获取用户信息

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

Get current user

获取当前用户信息

agent-teams user me
undefined
agent-teams user me
undefined

Reaction Commands

消息反应命令

bash
undefined
bash
undefined

Add reaction (use emoji name)

添加反应（使用emoji名称）

agent-teams reaction add <channel-id> <message-id> <emoji> agent-teams reaction add 19:abc123@thread.tacv2 1234567890 like
agent-teams reaction add <channel-id> <message-id> <emoji> agent-teams reaction add 19:abc123@thread.tacv2 1234567890 like

Remove reaction

移除反应

agent-teams reaction remove <channel-id> <message-id> <emoji>
agent-teams reaction remove <channel-id> <message-id> <emoji>

List reactions on a message

列出消息上的所有反应

agent-teams reaction list <channel-id> <message-id>
undefined
agent-teams reaction list <channel-id> <message-id>
undefined

File Commands

文件命令

bash
undefined
bash
undefined

Upload file

上传文件

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

List files in channel

列出频道中的文件

agent-teams file list <channel-id>
agent-teams file list <channel-id>

Get file info

获取文件信息

agent-teams file info <channel-id> <file-id>
undefined
agent-teams file info <channel-id> <file-id>
undefined

Snapshot Command

快照命令

Get comprehensive team state for AI agents:
bash
undefined
为AI Agent获取全面的团队状态：
bash
undefined

Full snapshot

完整快照

agent-teams snapshot
agent-teams snapshot

Filtered snapshots

过滤后的快照

agent-teams snapshot --channels-only agent-teams snapshot --users-only
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)
agent-teams snapshot --limit 10

返回的JSON包含：
- 团队元数据（id、名称）
- 频道（id、名称、类型、描述）
- 近期消息（id、内容、作者、时间戳）
- 成员（id、显示名称、邮箱）

Output Format

输出格式

JSON (Default)

JSON（默认）

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"
}
所有命令默认输出JSON格式，方便AI处理：
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
使用
--pretty
参数获取格式化输出：
bash
agent-teams channel list --pretty

Key Differences from Discord/Slack

与Discord/Slack的主要区别

FeatureTeamsDiscordSlack
Server terminologyTeamGuildWorkspace
Channel identifiersUUID format (19:xxx@thread.tacv2)Snowflake IDsChannel name or ID
Token storageCookies SQLiteLevelDBLevelDB
Token expiry60-90 minutesRarely expiresRarely 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.
特性TeamsDiscordSlack
服务器术语TeamGuildWorkspace
频道标识符UUID格式（19:xxx@thread.tacv2）Snowflake IDs频道名称或ID
Token存储Cookies SQLiteLevelDBLevelDB
Token有效期60-90分钟极少过期极少过期
提及格式
<at id="user-id">Name</at>
<@user_id>
<@USER_ID>
重要提示：Teams使用UUID格式的频道ID（例如
19:abc123@thread.tacv2
）。你不能直接使用频道名称——请先使用
channel list
命令查找ID。

Common Patterns

常见使用模式

See 
references/common-patterns.md
for typical AI agent workflows.
请查看
references/common-patterns.md
获取典型的AI Agent工作流。

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
请查看
templates/
目录获取可运行的示例：
  • post-message.sh
    - 带错误处理的消息发送脚本
  • monitor-channel.sh
    - 监控频道新消息（包含token刷新）
  • team-summary.sh
    - 生成团队摘要

Error Handling

错误处理

All commands return consistent error format:
json
{
  "error": "Not authenticated. Run \"auth extract\" first."
}
Common errors:
  • Not authenticated
    : No valid token - run 
    auth extract
  • Token expired
    : Token has expired (60-90 min limit) - run 
    auth extract
    again
  • 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 - re-authenticate immediately
所有命令返回一致的错误格式：
json
{
  "error": "未认证，请先运行\"auth extract\"。"
}
常见错误：
  • Not authenticated
    ：无有效token——运行
    auth extract
  • Token expired
    ：token已过期（60-90分钟限制）——重新运行
    auth extract
  • No current team set
    ：未设置当前团队——先运行
    team switch <id>
  • Message not found
    ：无效的消息ID
  • Channel not found
    ：无效的频道ID
  • 401 Unauthorized
    ：token已过期——立即重新认证

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)
凭证存储在：
~/.config/agent-messenger/teams-credentials.json
格式：
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"
    }
  }
}
安全性：文件权限设置为0600（仅所有者可读写）

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 - must re-authenticate frequently
  • 不支持实时事件/WebSocket连接
  • 不支持语音/视频频道
  • 不支持团队管理（创建/删除频道、角色）
  • 不支持会议功能
  • 不支持webhook
  • 仅支持纯文本消息（v1版本不支持自适应卡片）
  • 仅支持用户token（不支持应用token）
  • Token有效期为60-90分钟——必须频繁重新认证

Troubleshooting

故障排查

agent-teams: command not found

agent-teams: command not found

The 
agent-messenger
package is not installed. Run it directly using a package runner. Ask the user which one to use:
bash
npx -p agent-messenger agent-teams ...
bunx -p agent-messenger agent-teams ...
pnpm dlx --package agent-messenger agent-teams ...
If you already know the user's preferred package runner, use it directly instead of asking.
未安装
agent-messenger
包。请使用包运行器直接运行：
bash
npx -p agent-messenger agent-teams ...
bunx -p agent-messenger agent-teams ...
pnpm dlx --package agent-messenger agent-teams ...
如果你已经知道用户偏好的包运行器，请直接使用，无需询问。

References

参考资料

  • Authentication Guide
  • Common Patterns
  • 认证指南
  • 常见使用模式