Custom Agent-to-Agent Messaging Tool for v1 Architecture

Support
1

Custom Agent-to-Agent Messaging Tool for v1 Architecture

Author: Michael Hayes (Discord: michael_hayes)
Status: Community workaround for known A2A tool issues

Context

The built-in send_message_to_agent_async tool has known issues on both Cloud and self-hosted deployments. This is a working implementation of agent-to-agent communication for letta_v1_agent architecture.

Overview

This tool rebuilds send_message_to_agent_and_wait_for_reply as send_message_to_agent with compatibility for v1 agents. The implementation flow is the same except the system message sent to the recipient agent has been updated to return an assistant message instead of using the deprecated send_message tool.

Important: Agents migrated from memgpt_v2 may try to use the old send_message tool. You may need to add a system message explaining the agent has been migrated and clarifying the new rules.

Required Dependencies

  • Letta API key in the environment (LETTA_API_KEY)
  • New read-only agent_info core memory block that defines the agent_id

Tool Implementation

def send_message_to_agent(sender_agent_id: str, recipient_agent_id: str, message: str):
    """
    Send a message to another Letta agent in the same org and return the API response.

    Args:
        sender_agent_id: The ID of the agent that is sending the message (you).
        recipient_agent_id: The ID of the target agent to receive the message.
        message: The message content.

    Returns:
        The replies received from the recipient agent.
    """
    import os
    import requests
    import json

    letta_api_key = os.environ.get("LETTA_API_KEY")
    if not letta_api_key:
        return ("LETTA_API_KEY is not set in the environment.")

    response = requests.post(
        f"https://api.letta.com/v1/agents/{recipient_agent_id}/messages",
        headers={
            "Authorization": f"Bearer {letta_api_key}"
        },
        json={
            "messages": [
                {
                    "role": "system",
                    "content": [
                        {
                            "type": "text",
                            "text": f"[Incoming message from external Letta agent {sender_agent_id} - to reply to the requesting agent, simply send an assistant message with your response. The system will relay the message to the sender. send_message tool is now deprecated.] {message}"
                        }
                    ]
                }
            ]
        },
    )
    
    data = response.json()
    messages = data.get('messages', [])

    replies = [
        m['content']
        for m in messages
        if isinstance(m, dict)
        and m.get('message_type') == 'assistant_message'
        and m.get('content')
    ]

    return replies

Tool Schema

{
  "name": "send_message_to_agent",
  "description": "Sends a message to a specific Letta agent within the same organization and waits for a response. The sender's identity is included in sender_agent_id. This function is designed for two-way communication where a reply is expected.",
  "parameters": {
    "type": "object",
    "properties": {
      "sender_agent_id": {
        "type": "string",
        "description": "The ID of the sending Letta agent (e.g., your main agent)."
      },
      "recipient_agent_id": {
        "type": "string",
        "description": "The ID of the recipient Letta agent to receive the message."
      },
      "message": {
        "type": "string",
        "minLength": 1,
        "description": "The message content to deliver to the recipient agent."
      }
    },
    "required": [
      "sender_agent_id",
      "recipient_agent_id",
      "message"
    ]
  }
}

Setup Instructions

  1. Set environment variable:

    export LETTA_API_KEY="your_api_key"

  2. Create agent_info memory block (read-only):

    {
    "label": "agent_info",
    "value": "agent_id: agent-abc123",
    "description": "Read-only block containing this agent's ID"
}

  3. Add custom tool using the implementation above

  4. Attach tool to both agents (sender and recipient)

Migration Notes for v2 Agents

If migrating from memgpt_v2_agent to letta_v1_agent:

  • Agents may attempt to use the old send_message tool
  • Add a system instruction explaining the new architecture:
    You have been migrated to v1 architecture. The send_message tool is deprecated.
To communicate with other agents, use send_message_to_agent.
To respond to incoming agent messages, use assistant messages directly.

How It Works

  1. Sender agent calls send_message_to_agent with recipient ID and message
  2. Tool makes POST request to /v1/agents/{recipient_id}/messages
  3. System message includes sender ID and instructions for recipient
  4. Recipient agent generates assistant message (no tool call needed)
  5. Tool extracts assistant messages from response
  6. Replies returned to sender agent

Known Limitations

  • Synchronous only (waits for recipient response)
  • Requires API key in environment
  • Both agents must be in same organization

Related

Community contribution by Michael Hayes. Feel free to customize for your specific use case!