# Messaging Agents

> Messaging Agents is an Agent Skill for productivity published in the letta-ai/letta-code repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Send messages to other agents on your server. Use when you need to communicate with, query, or delegate tasks to another agent.

- Skill name: `messaging-agents`
- Category: [Productivity](https://www.openparable.com/skill/productivity/1)
- Source: https://github.com/letta-ai/letta-code/blob/HEAD/src/skills/builtin/messaging-agents/SKILL.md
- Repository: letta-ai/letta-code (2,850 GitHub stars when collected)

## SKILL.md

# Messaging Agents

This skill enables you to send messages to other agents on the same Letta server using the thread-safe conversations API.

## When to Use This Skill

- You need to ask another agent a question
- You want to query an agent that has specialized knowledge
- You need information that another agent has in their memory
- You want to coordinate with another agent on a task

## What the Target Agent Can and Cannot Do

**The target agent CANNOT:**
- Access your local environment (read/write files in your codebase)
- Execute shell commands on your machine
- Use your tools (Bash, Read, Write, Edit, etc.)

**The target agent CAN:**
- Use their own tools (whatever they have configured)
- Access their own memory blocks
- Make API calls if they have web/API tools
- Search the web if they have web search tools
- Respond with information from their knowledge/memory

**Important:** This skill is for *communication* with other agents, not *delegation* of local work. The target agent runs in their own environment and cannot interact with your codebase.

**Need local access?** If you need the target agent to access your local environment (read/write files, run commands), use the Agent tool instead to deploy them as a subagent:
```typescript
Agent({
  agent_id: "agent-xxx",            // Deploy this existing agent
  subagent_type: "general-purpose", // read-write access to your local tools
  prompt: "Look at the code in src/ and tell me about the architecture"
})
```
This gives the agent access to your codebase while running as a subagent.

## Finding an Agent to Message

If you don't have a specific agent ID, use these skills to find one:

### By Name or Tags
Load the `finding-agents` skill to search for agents:
```bash
letta agents list --query "agent-name"
letta agents list --tags "origin:letta-code"
```

### By Topic They Discussed
Load the `searching-messages` skill to find which agent worked on something:
```bash
letta messages search --query "topic" --all-agents
```
Results include `agent_id` for each matching message.

## CLI Usage (agent-to-agent)

### Starting a New Conversation

```bash
letta -p --from-agent $LETTA_AGENT_ID --agent <id> "message text"
```

When no `--environment` is specified, the target agent will run in the same
environment as the caller agent.

To route the target agent turn through a specific remote/local environment:

```bash
letta -p --from-agent $LETTA_AGENT_ID \
  --agent <id> \
  --environment <name-or-device-id-or-connection-id> \
  "message text"
```

**Arguments:**
| Arg | Required | Description |
|-----|----------|-------------|
| `--agent <id>` | Yes | Target agent ID to message |
| `--from-agent <id>` | Yes | Sender agent ID (injects agent-to-agent system reminder) |
| `--environment <selector>` | No | Route through an online environment by connection name, device ID, or connection ID |
| `"message text"` | Yes | Message body (positional after flags) |

**Example:**
```bash
letta -p --from-agent $LETTA_AGENT_ID \
  --agent agent-abc123 \
  "What do you know about the authentication system?"
```

**Response:**
```json
{
  "conversation_id": "conversation-xyz789",
  "response": "The authentication system uses JWT tokens...",
  "agent_id": "agent-abc123",
  "agent_name": "BackendExpert"
}
```

### Continuing a Conversation

```bash
letta -p --from-agent $LETTA_AGENT_ID --conversation <id> "message text"
```

Add `--environment <selector>` to continue the conversation on a specific environment.

### Discovering Environments

```bash
letta environments list --online-only
# alias:
letta envs list --online-only
```

Use `connectionName`, `deviceId`, or `connectionId` from the JSON output as the
`--environment` selector. If a name is ambiguous, prefer `deviceId` or
`connectionId`. In `environments list`, the current local runtime is marked with
`"isCurrent": true`.

To force the target agent onto the current registered Letta Code environment,
resolve the current environment and pass its `connectionId`:

```bash
CURRENT_ENV=$(letta environments current | jq -r .connectionId)
letta -p --from-agent $LETTA_AGENT_ID \
  --agent agent-abc123 \
  --environment "$CURRENT_ENV" \
  "Run on my same machine/environment."
```

Omit `--environment` when you want the target agent to run in the same
environment as the caller agent.

**Arguments:**
| Arg | Required | Description |
|-----|----------|-------------|
| `--conversation <id>` | Yes | Existing conversation ID |
| `--from-agent <id>` | Yes | Sender agent ID (injects agent-to-agent system reminder) |
| `"message text"` | Yes | Follow-up message (positional after flags) |

**Example:**
```bash
letta -p --from-agent $LETTA_AGENT_ID \
  --conversation conversation-xyz789 \
  "Can you explain more about the token refresh flow?"
```

## Understanding the Response

- Text-mode scripts return only the **final assistant message** (not tool calls, reasoning, or metadata)
- JSON and stream-json responses include `agent_id`, `conversation_id`, and `environment.source` so you can continue the same conversation/runtime. Environment-routed turns also include `environment.id`, `connection_id`, `device_id`, and `name`.
- The target agent may use tools, think, and reason - but you only see their final response
- To see the full conversation transcript (including tool calls), use the `searching-messages` skill with `letta messages list --agent <id>` targeting the other agent

## How It Works

When you send a message, the target agent receives it with a system reminder:
```
<system-reminder>
This message is from "YourAgentName" (agent ID: agent-xxx), an agent currently running inside the Letta Code CLI (docs.letta.com/letta-code).
The sender will only see the final message you generate (not tool calls or reasoning).
If you need to share detailed information, include it in your response text.
</system-reminder>
```

This helps the target agent understand the context and format their response appropriately.

## Hidden Conversations

Agent-to-agent conversations (started via `--from-agent`) are created **hidden** on the target agent. They don't appear in the target's default conversation list in the ADE, so automated inter-agent chatter doesn't clutter the UI.

To inspect them:
- List hidden conversations via the API with `archive_status=archived` (or `all`)
- Pull the transcript directly with `letta messages transcript --conversation <id>`
- The `conversation_id` returned when you sent the message is the handle you need

Continuing a hidden conversation with `--conversation <id>` keeps it hidden — only archive status is affected, messaging still works normally.

## Related Skills

- **finding-agents**: Find agents by name, tags, or fuzzy search
- **searching-messages**: Search past messages across agents, or view full conversation transcripts

---

Source: https://www.openparable.com/skill/productivity/messaging-agents (OpenParable). Cite the canonical URL above.
