agent.conversation

Instructions

Implementation Reference

• src/tools/messages.ts:62-85 (handler)

  The main handler function for agent.conversation. It validates agent_identifier and other_identifier, looks up both agents, calls getConversation() to retrieve the full conversation history, marks messages as read, and returns the result.

  export async function handleAgentConversation(args: Record<string, unknown>): Promise<ToolResult> {
    const agentIdentifier = (args.agent_identifier as string || "").trim();
    const otherIdentifier = (args.other_identifier as string || "").trim();
  
    if (!agentIdentifier) return { error: "agent_identifier is required" };
    if (!otherIdentifier) return { error: "other_identifier is required" };
  
    const agent = await getAgent(agentIdentifier);
    if (!agent) return { error: "Agent not registered. Call memory.register first." };
  
    const other = await getAgent(otherIdentifier);
    if (!other) return { error: "Other agent not found." };
  
    await updateAgentSeen(agent.id);
    const limit = Math.min((args.limit as number) || 50, 100);
    const messages = await getConversation(agent.id, other.id, limit);
  
    return {
      status: "ok",
      messages,
      count: messages.length,
      note: "Messages from the other agent have been marked as read.",
    };
  }

• src/tool-definitions.ts:695-721 (schema)

  The tool definition and input schema for agent.conversation. Defines required parameters (agent_identifier, other_identifier) and optional limit (max 100, default 50).

  {
    name: "agent.conversation",
    description:
      "View the full conversation history with another agent. " +
      "Shows all messages in both directions, chronologically. " +
      "Automatically marks received messages as read.",
    inputSchema: {
      type: "object",
      properties: {
        agent_identifier: {
          type: "string",
          description: "Your agent identifier (must be registered).",
        },
        other_identifier: {
          type: "string",
          description: "The other agent's identifier.",
        },
        limit: {
          type: "integer",
          minimum: 1,
          maximum: 100,
          description: "Max messages. Default: 50.",
        },
      },
      required: ["agent_identifier", "other_identifier"],
    },
  },

• src/server.ts:82-85 (registration)

  The switch-case registration in the MCP server's CallToolRequestSchema handler that routes 'agent.conversation' to handleAgentConversation.

  // DMs
  case "agent.message": result = await handleAgentMessage(safeArgs); break;
  case "agent.inbox": result = await handleAgentInbox(safeArgs); break;
  case "agent.conversation": result = await handleAgentConversation(safeArgs); break;

• src/server.ts:22-24 (registration)

  Import of handleAgentConversation from ./tools/messages.js into the server module.

  import {
    handleAgentMessage, handleAgentInbox, handleAgentConversation,
  } from "./tools/messages.js";